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PREFACE 


(TRS-80 is a trademark of the Tandy Corporation.) 


The TRS-80 is a capable machine, particularly so if it is programmed in its own (Z-80) assembly language. 
Assembly language programming is greatly facilitated by having a collection of general routines to draw 
upon. Your Level II ROM contains many useful routines, and one of the principal aims of this book is to 
provide the information necessary for utilizing these routines in your own assembly language programs. In 
Part 1 of the book, you will learn the locations of these routines, the optimum entry points for minimizing their 
calling sequences, and the setups and assembly language instructions required to call them. In addition, 
approximate execution times for the arithmetic and function routines are given. 

The second main objective of this book is to detail an efficient scheme for linking assembly language and 
BASIC programs. The result can be a single, smoothly joined program that combines the best features of both 
languages - the ease of writing, string capability, and input-output power of BASIC, together with the speed 
of execution of assembly language. It is not atypical for 25% of a given program (written wholly in BASIC) 
to require 95% of the operating time. If this time-critical part can be rewritten in assembly language and 
efficiently linked to the remainder of the BASIC program, one can enjoy the best of both worlds. Part II of 
this book tells how to achieve an efficient linkage. 

To take full advantage of the information in this book requires a knowledge of Z-80 assembly language 
programming. Readers with such knowledge who are also fortunate enough to own a TRS-80 without a disk 
should experience little difficulty in putting this information to immediate use. The presence of a disk 
complicates matters, principally because the Level II ROM has exits to DISK BASIC that are not always 
plugged up when the latter is not present, and also because there are (and will be) different versions of disk 
system software. Nevertheless, all the material of this book can be used with disk systems provided sufficient 
care is taken, and the book details exactly where and how special allowances for a disk need to be made. 


The information presented in this work is not theoretical. It is the result of direct experience and use by the 
authors, and is true and correct to the best of our knowledge. Mumford Micro Systems does not, however, 
assume any liability for the reliability of this information, or for any losses incurred through its use or misuse. 
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INTRODUCTION 


A. Representation of Numbers in TRS-80 

Both decimal and hexadecimal numbers will be employed in the explanations in this book. All memory 
addresses, and the contents of registers and memory cells, will be given in hexadecimal, with a postfixed H. 
Decimal numbers will be used in most other situations; where ambiguity might arise, decimal numbers will be 
distinguished by the legend "(decimal)". Pages 8/9 and 8/10 of the Level II Basic Reference Manual have 
brief descriptions of the internal representations of numbers in the TRS-80. It is the purpose of this section to 
expand upon those descriptions. 

A number may be represented in the TRS-80 in one of three different formats: integer, single precision, or 
double precision. (There is also a 16-bit positive integer format for addresses and line numbers that is 
discussed in Section 3.3 (b).) 

An integer is stored in two consecutive bytes of memory, or held in a register pair (BC, DE, or HL). The 
more significant byte is stored in the memory cell with the higher address, or in the B, D, or H register of a 
register pair. (Observe that the usual order of the bytes is reversed in memory storage. That is, the less 
significant byte, which would be written last in ordinary notation, will be the first to appear in a memory scan 
that proceeds in order of increasing addresses. The reason for this is that the Z-80 architecture requires it.) Bit 
7 (the leftmost, or most significant bit) of the more significant byte is the sign bit: 0 for a positive integer, 1 
for a negative integer. The largest positive integer that can be represented (a 0 sign bit followed by fifteen 1 
bits) is thus 32767. 

Negative integers are stored in two's complement form. Bit 7 of the more significant byte is 1. To find the 
absolute value of a negative integer, complement all the bits and add 1 to the resulting number. The absolute 
value of a negative integer cannot exceed 32768. 

EXAMPLE: DA5CH represents a negative integer. To find out what negative integer it represents, first 
complement all bits by subtracting it from FFFFH: FFFFH - DA5CH = 25A3H. Then add 1: 
25A3H + 1 = 25A4H. Since 25A4H represents 9636 (decimal), the original hexadecimal number 
represents -9636. 

A number in single precision format is stored in four consecutive bytes of memory, or in two register pairs. 
The first byte (stored in the memory cell with the highest address) contains the exponent (on base 2) in excess 
128 format. That is, the true exponent is 128 (decimal) less than the number represented by the exponent byte. 
(All bits in the exponent byte have their normal meaning; thus, the exponent byte can represent any integer 
from 0 to 255, inclusive.) 

EXAMPLES: An exponent byte of CFH represents an actual exponent of 79 (decimal), because CFH = 207 
(decimal), and 207 - 128 = 79. Likewise, an exponent byte of 3DH represents an actual 
exponent of -67 (decimal), because 3DH = 61 (decimal), and 61 - 128 = -67. 

In single precision format, an exponent byte of 0 is used to signify the number 0, in which case the 
remaining three bytes have no effect upon the processing of the number. Otherwise (that is, exponent byte not 
0), the remaining three bytes (called the mantissa) are assumed to have a binary point in front of the most 
significant bit (bit 7 of the most significant byte of these three). (Again, the significance of the bytes increases 
with increasing memory addresses, so that the bytes of a single precision number will appear in memory to be 
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reversed from their "natural" order.) Also, it is assumed that the most significant bit is a 1, so that the mantissa 
of any nonzero single precision number always represents a fraction greater than or equal to 1/2 and smaller 
than 1. (This is normalized floating point representation.) The mantissa is, of course, to be multiplied by 2 to 
the power of E - where E is the true exponent (exponent byte less 128) - to get the single precision number 
represented. 

Since the most significant bit of the mantissa is always assumed to be 1, the actual most significant bit is 
free to be used as a sign bit (0 for +, 1 for -). This device allows the representation of numbers with one more 
bit of precision than if a separate bit were provided for the sign. 

A positive single precision number and its corresponding negative number are represented in exactly the 
same way except for the sign bit (bit 7 of the second byte). There is no two's complement form as there is in 
integer representation. 

EXAMPLES: (In these examples the four bytes of each single precision number are given in hexadecimal, 
with the exponent byte first, the most significant byte of the mantissa second, and the least significant byte 
last.) 

(a) 82H, 40H, 0, 0 represents 2 to the power of 2 multiplied by .110000000000000000000000 (the mantissa 

being given in binary), or 3.0 (decimal). Note the 1 supplied immediately after the binary point; this 
is automatic. The 1 in the second position following the binary point comes from the 40H 
expressed in binary. 

(b) 82H, C0H, 0, 0 represents -3.0 (decimal). Here the minus sign occurs because the second byte has a 1 in 

bit 7; this 1 becomes the (negative) sign, and a new 1 is then automatically supplied for the 
mantissa. 

(c) Let's analyze the single precision number represented by 84H, 67H, 80H, 0. First, the exponent byte 

(84H) represents a true exponent of 4, since 84H =132 (decimal), and 132 - 128 = 4. Next, the 
most significant bit of the mantissa is 0, since 67H has 0 in its leftmost bit position. Therefore, the 
number represented is positive. Now, 67H is 01100111 in binary, and the bytes following it (80H, 
0) expand this to binary 

0110 0111 1000 0000 0000 0000 

Next we supply the automatic 1 in the most significant bit: 

1110 0111 1000 0000 0000 0000 

The exponent 4 means that the binary point is placed between the 4th and 5th bits from the left: 
1110.0111 1000 0000 0000 0000 

Drop the trailing zeroes to get 

1110.01111 

This is equal to 8 + 4 + 2 + 0 + 0/2 + 1/4 + 1/8 + 1/16 + 1/32 =14+ 15/32 = 14.46875 (decimal). 
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Converting decimal numbers to single precision format is a necessary operation for assembly language 
programming of arithmetic procedures, but the above discussion and examples may have dampened your 
enthusiasm for such conversions. If so, you may use routines in the Level II ROM to perform the conversions; 
methods for doing this will be given in Section 3.4 (a). 

A number in double precision format is stored in eight consecutive bytes of memory. This format is 
identical to single precision format except that the mantissa has four additional (low order) bytes of precision. 
(Again the bytes will appear in memory in the reverse of "natural" order.) Just as in single precision format, 
nonzero numbers with absolute values in the range of 2 to the power of -128 to 2 to the power of+127 can be 
represented. 


B. Use of Registers 

Using the Z-80 registers for temporary storage of characters, one and two byte integers, and addresses can 
be extremely effective in minimizing the size and execution time of an assembly language program. Almost 
all of the ROM subroutines described in this book use the registers for their own purposes without saving and 
restoring their contents. It follows that you should not expect any register to be returned with its contents 
intact after a call to a ROM subroutine. If you wish to save a register (pair), PUSH it onto the stack before the 
subroutine call and POP it off again after the return. 


C. Links to DISK BASIC 

A number of ROM subroutines contain calls to addresses in reserved RAM. In diskless systems, these 
RAM addresses hold subroutine returns that immediately terminate the calls. In a system with a disk, 
however, these RAM addresses may hold jumps to DISK BASIC enhancement routines. As long as DISK 
BASIC is present when your assembly language program uses these ROM subroutines, there will be no 
problem. However, if you read your assembly language program from disk and execute it directly, DISK 
BASIC may not be present, and the "leaks" from reserved RAM to DISK BASIC may not be plugged. The 
result can be a random jump, necessitating a reinitialization of DOS. There are two ways to avoid this 
embarrassment. One is to make sure that DISK BASIC is present before running your assembly language 
program that uses ROM subroutines; this can be done by employing the LOAD command to read the program 
from disk, then transferring to BASIC and using the SYSTEM command to commence execution of the 
program. The other method is for your assembly language program to store RETums (C9H) in the reserved 
RAM locations that are called by the ROM subroutines that it uses. The information that you need to 
implement this second method will be found in subsequent sections; each sensitive subroutine will be 
indicated, and the RAM addresses that need to be plugged will be identified. 

Relatively few of the ROM routines to be described in this book - and none of the conversion, arithmetic, 
or function routines - have direct exits to DISK BASIC. Nevertheless, many routines have the (remote) 
potential of transferring control to the Level II monitor because of operational errors - overflow, divide by 
zero, illegal function call, etc. And the Level II monitor has many exits to DISK BASIC. A blunderbuss 
approach to the problem of "leaks" would be to store RETums in all RAM locations that might cause trouble. 
A complete list of these addresses is: 400CH and twenty-one locations starting at 41A6H and proceeding in 
steps of 3 (41A6H, 41A9H, 41ACH, etc.). Here is an assembly language segment that you could use at the 
beginning of your assembly language program to store RET's in all the aforementioned locations: 
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LOOP 


LD 

A, 0C9H 

LD 

(400CH),A 

LD 

HL,41A6H 

LD 

B.15H 

LD 

(HL),A 

INC 

HL 

INC 

HL 

INC 

HL 

DJNZ 

LOOP 


FINAL NOTE: The transfer point at 400CH is actually an exit to DOS that is taken when the BREAK key is 
depressed. If you store a RET in this location, you should restore the JP (C3H) that is normally there before 
exiting to the operating system. Failure to restore this JP can result in a reinitialization of DOS. 
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PARTI 


The Level II ROM and Reserved RAM 

CHAPTER 1 

Key Locations and Entry Points 


1.1 Reserved RAM Storage Locations 

The TRS-80 memory map on pages D/1 and D/2 of the Level II Basic Reference Manual shows that 
memory locations 4000H through 42E8H are reserved for the use of the Level II monitor. The most 
significant of these locations are listed below, together with their functions. 

4016H-4017H: Hold the entry point address of the keyboard driver. 

401EH-401FH: Hold the entry point address of the video driver. 

4020H-4021H: Hold the video memory address of the current cursor position. 

4026H-4027H: Hold the entry point address of the line printer driver. 

408EH-408FH: Used to hold the entry address of a machine language program called by the USR 
command. 

40A0H-40A1H: Hold the address of the start of the string storage area. 

40A4H-40A5H: Hold the starting address of BASIC program text. 

40A7H-40A8H: Hold the beginning address of the keyboard input buffer. 

40AAH-40ACH: Hold the three bytes of seed number for the random number generator. 

40AFH: Holds a flag indicating the type of the variable being processed by a ROM routine. Thi s flag has 
value 2 for an integer variable, 3 for a string variable, 4 for a single precision variable, or 8 for a 
double precision variable. 

40B1H-40B2H: Hold the MEMORY SIZE (top of the unprotected RAM). 

40DFH-40E0H: Hold the entry point address for a SYSTEM tape that has just been read. (This address 
may be destroyed by execution of a BASIC program.) 

40F9H-40FAH: Hold the starting address of the BASIC simple variable storage area. 
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40FBH-40FCH: Hold the starting address of the BASIC array variable storage area. 


40FDH-40FEH: Hold the starting address of the BASIC free memory area. 

411DH-4124H: Provide a buffer area for a double precision variable to be processed. 

4121H-4122H: Provide a buffer area for an integer variable to be processed. 

4121H-4124H: Provide a buffer area for a single precision variable to be processed. 

4127H-412EH: Provide a buffer area for a second double precision variable to be processed. 

41A9H-41ABH: Here may be stored a machine language jump to a routine that expands the number of 
available USR calls. 

41E8H-42E7H: Provide a buffer area for keyboard input in systems without disks. 


1.2 Entry Points for Level II Commands and Functions 

Table 1.2 shows the ROM entry points for the Level II commands and functions. (Arithmetic operations 
have several entry points each; these entry points will be given in Chapter 4.) 

Many of the subroutines that implement these commands and functions will be described more fully in later 
sections of this book, where the recommended entry points may differ from those presented here. The reason 
for the differences is that the entry points to be given later have been chosen for their efficiency; the locations 
in Table 1.2 are the ones actually used by the Level II monitor. 


1.3 Transfer points for DISK BASIC Commands 

The Level II ROM transfers certain DISK BASIC commands to addresses in reserved RAM. In a disk- 
based system, these locations are filled with jumps to DISK BASIC, but in a diskless system the locations are 
filled with jumps to 012DH. (A jump to 012DH causes "?L3 ERROR" to be displayed.) If you have a system 
with no disk, you may thus add new commands to your computer by filling some of these locations with 
jumps to your own assembly language program that implements the new commands. Table 1.3 lists these 
DISK BASIC commands and their transfer points in reserved RAM. 

The Z-80 RST instruction is a special one-byte subroutine call to a low memory address. The Level II 
ROM transfers seven of these RST's to addresses in reserved RAM, from which points they are turned back 
into the ROM or transferred again to DISK BASIC. By filling some of these RAM locations with jumps to 
your own assembly language program, you can provide that program with low-overhead calls to frequently 
used subroutines. (Caution: Use of this technique will disable many ROM subroutines. Be sure that they aren't 
ones that you are using in your assembly language program.) Here are the RST's and their reserved RAM 
transfer points: 


RST 8 

4000H 

RST 28H 

400CH 

RST 10H 

4003H 

RST 30H 

400FH 

RST 18H 

4006H 

RST 38H 

4012H 

RST 20H 

4009H 
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Table 1.2 - Level II Entry Points 


ABS 

0977H 

LIST 

2B2EH 

ASC 

2A0FH 

LLIST 

2B29H 

ATN 

15BDH 

LOG 

0809H 

AUTO 

2008H 

LPRINT 

2067H 

CDBL 

0ADBH 

MID$ 

2A9AH 

CHR$ 

2A1FH 

MEM 

27C9H 

CINT 

0A7FH 

NEW 

1B49H 

CLEAR 

1E7AH 

NEXT 

22B6H 

CLOAD 

2C1FH 

NOT 

25C4H 

CLS 

01C9H 

ON 

1F6CH 

CONT 

1DE4H 

OUT 

2AFBH 

COS 

1541H 

PEEK 

2CAAH 

CSAVE 

2BF5H 

POINT 

0132H 

CSNG 

0AB1H 

POKE 

2CB1H 

DATA 

1F05H 

POS 

27F5H 

DEFDBL 

1E09H 

PRINT 

206FH 

DEFINT 

1E03H 

RANDOM 

01D3H 

DEFSNG 

1E06H 

READ 

21EFH 

DEFSTR 

1E00H 

REM 

1F07H 

DELETE 

2BC6H 

RESET 

0138H 

DIM 

2608H 

RESTORE 

1D91H 

EDIT 

2E60H 

RESUME 

1FAFH 

ELSE 

1F07H 

RETURN 

1EDEH 

END 

1DAEH 

RIGHTS 

2A91H 

ERL 

24DDH 

RND 

14C9H 

ERR 

24CFH 

RUN 

1EA3H 

ERROR 

1FF4H 

SET 

0135H 

EXP 

1439H 

SGN 

098AH 

FIX 

0B26H 

SIN 

1547H 

FOR 

1CA1H 

SQR 

13E7H 

FRE 

27D4H 

STOP 

1DA9H 

GOSUB 

1EB1H 

STR$ 

2836H 

GOTO 

1EC2H 

STRINGS 

2A2FH 

IF 

2039H 

SYSTEM 

02B2H 

INKEYS 

019DH 

TAN 

15A8H 

INP 

2AEFH 

TROFF 

1DF8H 

INPUT 

219AH 

TRON 

1DF7H 

INT 

0B37H 

USR 

27FEH 

LEFTS 

2A61H 

VAL 

2AC5H 

LEN 

2A03H 

VARPTR 

24EBH 

LET 

1F21H 
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Table 1.3 - Disk Basic Entry Points 


CLOSE 

4185H 

LOC 

4164H 

CMD 

4173H 

LOF 

4167H 

CVD 

415EH 

LSET 

4197H 

CVI 

4152H 

MERGE 

418BH 

CVS 

4158H 

MKD$ 

4170H 

DEF 

415BH 

MKI$ 

416AH 

EOF 

4161 H 

MKS$ 

416DH 

FIELD 

417CH 

NAME 

418EH 

FN 

4155H 

OPEN 

4179H 

GET 

417FH 

PUT 

4182H 

INSTR 

419DH 

RSET 

419AH 

KILL 

4191 H 

SAVE 

41A0H 

LINE 

41A3H 

TIMES 

4176H 

LOAD 

4188H 

& 

4194H 
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CHAPTER 2 

Registers, Buffers, and Variable Passage 


2.1 Variable Buffers and Holding Registers 

Nearly all of the Level 11 ROM routines to be detailed in Chapters 3, 4, and 5 require one or two input 
variables and return the value of an output variable. These routines expect to receive their inputs in certain 
common locations and/or registers and also deliver their outputs in common locations and/or registers. The 
following paragraphs describe these common modes of input-output variable passage. (The pertinent part of 
this information will be concisely repeated for each routine in Chapters 3, 4, and 5.) 

Integer variables are passed through the HL register pair, the DE register pair, and the memory locations 
4121H-4122H. Specifically, if a routine requires a single integer input, that input is passed through HL, or, for 
certain routines, through locations 4121H-4122H. If a routine requires two integer inputs, these are passed 
through the HL and DE register pairs. In all cases, an integer output is stored in memory locations 
4121H-4122H and also (except for one routine in Section 3.4) in the HL register pair. 

Single precision variables are passed through memory locations 4121H-4124H and (in the case of a two- 
input routine) through the four registers BCDE. Specifically, if a routine requires one single precision input, 
that input is passed through memory locations 4121H-4124H, while two single precision inputs are passed 
using this memory area for one and registers BCDE for the other. (Register B contains the exponent, C the 
most significant byte of the mantissa, and E the least significant byte of the mantissa.) In all cases a single 
precision output will be stored in memory locations 4121H-4124H. 

Double precision variables are passed through (1) memory locations 411DH-4124H and (2) memory 
locations 4127H-412EH. Locations 411DH-4124H are used for a single (or first) input and for any output. 
Locations 4127H-412EH hold the second of two inputs. 


2.2 Subroutines to Move Variables 

Use of the ROM routines of Chapters 3, 4, and 5 requires the movement of variables between storage and 
the number buffer areas mapped out in the previous section, as well as between storage and the BCDE 
registers. There are several ROM subroutines that may be used to effect these movements for single precision 
variables. 

(a) To move a single precision variable from storage to the buffer area 4121H-4124H, load the HL register 

pair with the starting memory address of the variable (the address of the least significant byte) and 
CALL 09B1H. To move a single precision variable from the buffer area 4121H-4124H to memory, 
starting at the address contained in the HL register pair, CALL 09CBH. 

(b) To transfer a single precision variable from registers BCDE to the buffer area 4121H-4124H, CALL 

09B4H. To transfer a single precision variable from the buffer area 4121H-4124H to the registers 
BCDE, CALL 09BFH. 

(c) To transfer a single precision variable from storage to the registers BCDE, load the HL register pair with 

the starting memory address of the variable and CALL 09C2H. 
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(d) To move a single precision variable from the buffer area 4121H-4124H to the stack, CALL 09A4H. In 
retrieving this variable from the stack, execute a POP BC followed by a POP DE; the variable bytes 
will then be in normal order in the BCDE registers. 
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CHAPTER 3 

Conversion Routines 


3.1 Single Precision to Integer 

The Level 11 ROM has three subroutines that convert single precision variables to integer variables. CINT 
always converts to an integer (using the greatest integer function) except when the input variable has absolute 
value greater than 32767, in which case an OV error occurs, returning control to the Level 11 monitor. INT 
will convert to an integer when possible (also using the greatest integer function), but will leave the result in 
single precision format (adjusted to a whole number) whenever the absolute value of the result exceeds 32767. 
Finally, FIX behaves like INT except that the whole number result is obtained by truncation. That is, 
FIX(-3.2) = -3, while INT(-3.2) = -4. Here are the details of using these routines: 

(a) CINT Follow these steps: 

(1) Store the input variable (in single precision format) in memory locations 4121H-4124H. 

(2) CALL 0A8AH. 

The integer result will be in 4121H-4122H and in the HL register pair. Overflow results in an OV error. 

(b) INT Follow these steps: 

(1) Store the input variable (in single precision format) in memory locations 4121H-4124H. 

(2) Store a 4 in 40AFH. 

(3) CALL 0B3DH. 

The result (in integer format) will be in 4121H-4122H and in the HL register pair if the absolute value of the 
input variable does not exceed 32767. Otherwise, the result will be in 4121H-4124H in single precision 
format, but adjusted to a whole number. Location 40AFH will contain a 2 if the result is in integer format, or a 
4 if the result is in single precision format. 

(c) FIX Follow these steps: 

(1) Store the input variable, which may be either single or double precision, in 4121H-4124H (if single 

precision), or in 411DH-4124H (if double precision). 

(2) Store the variable type (4 for single precision, or 8 for double precision) in location 40AFH. 

(3) CALL 0B26H. 

If the result can be stored in integer format, it will be in 4121H-4122H and in HL. Otherwise, it will be in 
4121H-4124H (if input was single precision) or in 411DH-4124H (if input was double precision). Location 
40AFH will contain a 2, 4, or 8 for integer, single precision, or double precision output, respectively. 


3.2 Integer to Single Precision 

The following steps activate a routine in ROM that converts an integer to single precision format: 

(1) Store the input integer in 4121H-4122H. 

(2) CALLOACCH. 

The result (in single precision format) is in 4121H-4124H. 
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3.3 Number to Numeric String 

(a) To convert an integer, single precision, or double precision variable to its corresponding character string, 
follow these steps: 

(1) Store the variable in 4121H-4122H (if an integer), or in 4121H-4124H (single precision), or in 

411DH-4124H (double precision). 

(2) Store the variable type (2, 4, or 8, respectively) in location 40AFH. 

(3) CALL OFBDH. 

Upon return the character string is stored in locations 4130H and following, with a zero byte at the end. The 
FIL register pair contains 4130H. Thus, the setup for video display of the character string - using the 
subroutine that will be described in Section 8.2 (b) - is complete. 

(b) Besides the two's complement integer format, there is a special 16-bit positive integer format that is used 
by the TRS-80 for line numbers and memory addresses. In this format no negative numbers may be 
represented, but positive integers up to 65535 are allowed. 

EXAMPLE: In positive integer format, C5A3FI represents 50595 (decimal). The same hexadecimal number 
in standard (two's complement) integer format would represent -14941 (decimal). 

To convert a number in 16-bit positive integer format to its corresponding character string, first load the 
number into the FIL register pair, and then execute the following instructions: 


CALL 

0A9AH 

XOR 

A 

CALL 

1034H 

OR 

(HL) 

CALL 

0FD9H 


Upon return from the subroutine at 0FD9H, the character string will be in memory locations 4130H- 
4135H, right justified, with a zero byte in 4136H. On the left, the string is filled with spaces up to the leading 
digit. The HL register pair contains the address of the last space (the one just before the leading digit). Thus, if 
the subroutine of Section 8.2 (b) is used immediately to display the character string, it will appear with one 
leading space. (To suppress the leading space, simply INC HL before calling the subroutine of Section 8.2 

m 


3.4 Numeric String to Number 

(a) To convert a numeric string to a number in integer, single precision, or double precision format, follow 
these steps: 

(1) Have the characters assembled in consecutive memory locations, with either a comma or a zero byte at 

the end. 

(2) Load HL with the address of the first character. 

(3) CALL 0E6CH. 

The routine at 0E6CH converts to an integer if possible, with the result in 4121H-4122H and a 2 (for integer 
variable) in 40AFH. Otherwise, it converts to a single precision variable (with the output in 4121H-4124H 
and a 4 in 40AFH), or to a double precision variable (with the output in 411DH-4124H and an 8 in 40AFH). 
(The double precision option is exercised if the input string has more than 7 digits.) 
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If it is desired that the input be converted to double precision format regardless of the number of digits 
entered, follow the above steps (1) and (2), but (step (3)) CALL 0E65H instead. The output will be in 
411DH-4124H, with an 8 in 40AFH. 

The above method may be used to convert decimal constants needed by your assembly language program 
to machine format. Suppose, for example, that you require a single precision value for pi. Somewhere in your 
assembly language program you could write the following lines of code: 

PISTR DEFM '3.141593' 

DEFB 0 

(The DEFM and DEFB are assembler pseudo-ops for defining the contents of memory locations.) Then, 
when pi is needed, execute these instructions: 

LD HL,PISTR 

CALL 0E6CH 

Upon return, the value of pi in single precision format will be in 4121H-4124H. 

If several different constant conversions are required, a subroutine (named LOAD below) could be written 
to effect the equivalent of an "immediate load" each time a constant is needed. Here is a coding for such a 
subroutine: 


POP 

HL 

CALL 

0E6CH 

INC 

HL 

PUSH 

HL 

RET 



When a value is required - say pi - execute the following: 

CALL LOAD 

DEFM '3.141593,' 

(Note the comma terminating the string. Either that or a zero byte will do.) After execution of the above code 
the correctly converted value of pi will be in the buffer area 4121H-4124H. 

Of course, the subroutine at 0E65H (to convert to double precision format) may be used instead of the one 
at 0E6CH in either of the above conversion procedures. 

(b) It is also possible to convert a character string representing an integer between 0 and 65535, inclusive, to 
16-bit positive integer format (discussed in the previous section). To do this, have the characters stored in 
consecutive locations in memory with a zero byte at the end. (The terminating zero byte is essential for this 
conversion routine.) Load the HL register pair with the address of the first character and CALL 1E5AH. The 
converted integer will be in the DE register pair upon return. (If the converted value of the string would 
exceed 65535, an SN error will occur, with control passing to the Level II monitor.) 
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CHAPTER 4 

Arithmetic Operations 


4.1 Addition 

There are three addition routines in the Level 11 ROM: one for integer operands, one for single precision 
operands, and one for double precision operands. 

(a) To add two integers, follow these steps: 

(1) Store one input in the DE register pair and the other in the HL register pair. 

(2) CALL 0BD2H. 

The result is in 4121H-4122H and in HL, with a 2 in 40ALH. 

EXCEPTION: In case of overflow, the result is converted to single precision format and stored in 
4121H-4124H, with a 4 in 40ALH. (Overflow causes no error.) 

TIME: Integer addition requires approximately 130 microseconds. 

(b) To add two single precision numbers, follow these steps: 

(1) Store one input in the BCDE registers - exponent in B, least significant byte in E. Store the other input 

in 4121H-4124H. 

(2) CALL 0716H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 630 microseconds. 

(c) To add two double precision numbers, follow these steps: 

(1) Store the operands in 411DH-4124H and in 4127H-412EH. 

(2) CALL 0C77H. 

The result (in double precision format) is in 411DH-4124H. 

TIME: Approximately 1.3 milliseconds. 


4.2 Subtraction 

Again, there are three subtraction routines. 

(a) To subtract two integers, follow these steps: 

(1) Store the minuend (first number) in the DE register pair, and store the subtrahend (number to be 

subtracted) in the HL register pair. EXAMPLE: To calculate 26 - 17, store 26 in DE and 17 in HL. 

(2) CALL 0BC7H. 

The result is in 4121H-4122H and in HL, with a 2 in 40AFH. 

EXCEPTION: In case of overflow, the result is converted to single precision format and stored in 
4121H-4124H, with a 4 in 40AFH. (Overflow causes no error.) 

TIME: Approximately 210 microseconds. 
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(b) To subtract two single precision numbers, proceed as follows: 

(1) Store the minuend in the BCDE registers and store the subtrahend in 4121H-4124H. 

(2) CALL 0713H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 670 microseconds. 

(c) To subtract two double precision numbers, proceed as follows: 

(1) Store the minuend in 411DH-4124H and the subtrahend in 4127H-412EH. 

(2) CALL 0C70H. 

The result (in double precision format) is in 411DH-4124H. 

TIME: Approximately 1.3 milliseconds. 


4.3 Multiplication 

There are also three multiplication routines. 

(a) To multiply two integers, follow these steps: 

(1) Store one input in DE, the other in HL. 

(2) CALL 0BF2H. 

The result is in 4121H-4122H and in HL, with a 2 in 40AFH. 

EXCEPTION: In case of overflow, the result is converted to single precision format and stored in 4121H- 
4124H, with a 4 in 40AFH. (Overflow causes no error.) 

TIME: Approximately 900 microseconds. 

(b) To multiply two single precision numbers, proceed as follows: 

(1) Store one operand in the BCDE registers, the other in 4121H-4124H. 

(2) CALL 0847H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 2.2 milliseconds. 

(c) To multiply two double precision numbers: 

(1) Store one operand in 411DH-4124H, and store the other in 4127H-412EH. 

(2) CALL 0DA1H. 

The result (in double precision format) is in 411DH-4124H. 

TIME: Approximately 22 milliseconds. 


4.4 Division 

(a) To divide two integers: 

(1) Store the dividend in the DE register pair, and store the divisor in HL. EXAMPLE: To calculate 26/7, 

store 26 in DE and 7 in HL. 

(2) CALL 2490H. 

The result is stored in single precision format (since it is not likely to be an integer) in 4121H-4124H. 

TIME: Approximately 5.1 milliseconds. 
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(b) To divide two single precision numbers: 

(1) Store the dividend in registers BCDE, and the divisor in 4121H-4124H. 

(2) CALL 08A2H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 4.8 milliseconds. 

(c) To divide two double precision numbers: 

(1) Store the dividend in 411DH-4124H, and the divisor in 4127H-412EH. 

(2) CALL 0DE5H. 

The result (in double precision format) is in 411DH-4124H. 

TIME: Approximately 42 milliseconds. 

NOTE: All the division routines are subject to OV or /0 errors, which return control to the Level II monitor. 


4.5 Exponentiation 

To raise a single precision number (the base) to a single precision power (the exponent), follow these steps: 

(1) Store the base (single precision) in registers BCDE, and store the exponent (also single precision) in 

4121H-4124H. 

(2) CALL 13F7H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 50 milliseconds. 

NOTE: Fatal errors, returning control to the Level 11 monitor, can occur in the following ways: 

(a) If the base is negative, and the exponent is not a whole number. 

(b) If the absolute value of the result is as large as 2 to the power of 127. 

(c) If the base is zero, and the exponent is negative. 

4.6 Comparison 

Comparison is the operation of determining which of two numbers is the larger. Comparison can obviously 
be effected by a subtraction followed by testing the sign of the result. However, the routines described below 
are faster than the corresponding subtraction routines. In each of these routines, the result of the comparison is 
specified in exactly the same way by the following states of the Z-80 flags (which should be tested 
immediately after return from the routine): 


If the numbers are equal, the Z (zero) flag will be set. If they are not equal, the Z 
flag will be turned off. If the first input number is the smaller, the S (sign) and C 
(carry) flags will also be turned off. If the second input number is the smaller, 
the S and C flags will both be set. (The phrases "first input" and "second input" 
are used consistently in this paragraph and the following descriptions.) 
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(a) To compare two integers: 

(1) Store the first input in DE, the second in HL. 

(2) CALL 0A39H. 

Interpret the result as explained in the preceding paragraph. 

(b) To compare two single precision numbers: 

(1) Store the first input in registers BCDE, the second input in 4121H-4124H. 

(2) CALLOAOCH. 

Interpret the result as explained above. 

(c) To compare two double precision numbers: 

(1) Store the first input in 411DH-4124H, and store the second input in 4127H-412EH. 

(2) CALL 0A78H. 

Interpret the result as explained above. 

(d) The Level II ROM has a special, very fast routine for comparing two integers in 16-bit positive integer 

format (which is described in Section 3.3 (b).) To use this special routine, proceed as follows: 

(1) Store the first input in DE, the second in HL. 

(2) RST 18H. The RST (restart) is a special one-byte subroutine call. 

Interpret the result as explained in the paragraph preceding (a) above. 
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CHAPTER 5 

Mathematical Functions 


Each of the functions presented in this chapter requires one input variable and returns the value of one 
output variable. The first seven of these functions require their inputs in single precision format and return 
single precision outputs. 


5.1 SQR 

To find the square root of a nonnegative single precision number: 

(1) Store the number in 4121H-4124H. 

(2) CALL 13E7H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 48 milliseconds. 

NOTE: A fatal error (returning control to the Level II monitor) occurs if the input number is negative. 


5.2 EXP 

To find EXP(X), where X is a single precision variable: 

(1) Store the value ofXin4121 H-4124H. 

(2) CALL 1439H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 28 milliseconds. 

NOTE: A fatal error occurs if the result is as large as 2 to the power of 127. 


5.3 LOG 

To find LOG(X), where X is a positive single precision variable: 

(1) Store the value ofXin4121 H-4124H. 

(2) CALL 0809H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 19 milliseconds. 

NOTE: A fatal error occurs if the value of the input variable is zero or negative. 


5.4 SIN 

To find SIN(X), where X is a single precision variable: 

(1) Store the value ofXin4121 H-4124H. 

(2) CALL 1547H. 

The result (in single precision format) is in 4121H-4124H. 
TIME: Approximately 25 milliseconds. 

NOTE: The argument (X) must be in radians. 
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5.5 COS 


To find COS(X), where X is a single precision variable (in radians): 

(1) Store the value ofXin4121 H-4124H. 

(2) CALL 1541H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 25 milliseconds. 


5.6 TAN 

To find TAN(X), where X is a single precision variable (in radians): 

(1) Store the value ofXin4121 H-4124H. 

(2) CALL 15A8H. 

The result (in single precision format) is in 4121H-4124H. 

TIME: Approximately 54 milliseconds. 

NOTE: A fatal error occurs if the result is as large as 2 to the power of 127, which will be the case if the value 
of X is sufficiently close to any odd multiple of pi/2 radians. 


5.7 ATN 

To find ATN(X), where X is a single precision variable: 

(1) Store the value ofXin4121 H-4124H. 

(2) CALL 15BDH. 

The result (in single precision format, in radians) is in 4121H-4124H. 
TIME: Approximately 27 milliseconds. 


5.8 SGN 

The signum function returns the value -1, 0, or +1, depending upon whether the input variable is negative, 
zero, or positive, respectively. The input can be an integer, single precision, or double precision number. To 
find SGN(X), proceed as follows: 

(1) Store the value of X in 4121H-4122H (integer), in 4121H-4124H (single precision), or in 

411DH-4124H (double precision). 

(2) Store the variable type (2, 4, or 8, respectively) in 40AFH. 

(3) CALL 098AH. 

The result (in integer format) is in 4121H-4122H and in the HL register pair. 


5.9 ABS 

The input variable may be integer, single precision, or double precision. The output is in the same format as 
the input. To find ABS(X), proceed as follows: 

(1) Store the value of X in 4121H-4122H (integer), in 4121H-4124H (single precision), or in 411DH- 
4124H (double precision). 
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(2) Store the variable type (2, 4, or 8, respectively) in 40AFH. 

(3) CALL 0977H. 

The result (in the same format as the input variable) is in the same locations in which the input variable was 
stored. If the input was an integer, the result is also in the HL register pair. 


5,10 Random Number Generation 

(a) The random number generator keeps its 24-bit seed number in memory locations 40AAH-40ACH. You 
may store any collection of bits in these locations to provide a (repeatable) starting point for random number 
generation in your programs. The RANDOM function in BASIC causes the contents of the R (memory 
refresh) register to be stored in location 40ABH. To accomplish this in assembly language programs, simply 
CALL 01D3H. 

(b) The RND(O) function in BASIC returns a single precision random number between 0 and 1, exclusive. To 
do the same thing in assembly language, CALL 14F0H. No input variable is necessary. The result (in single 
precision format) is in 4121H-4124H. 

TIME: Approximately 2.4 milliseconds. 

(c) The RND(J) function (with J a nonzero integer) is a BASIC function that returns a random integer 
between 1 and J, inclusive. To do the same thing in assembly language, proceed as follows: 

(1) Load the value of J into the HL register pair. 

(2) CALL 14CCH. 

(3) CALL 0A7FH. 

The result (in integer format) is in 4121H-4122H and in HL. 

TIME: Approximately 5.7 milliseconds. 

NOTES: The input variable J must have a value between 1 and 32767, inclusive, or an FC error will occur, 
returning control to the Level II monitor. The CALL in step (3) above is to convert the single precision 
number produced by the routine at 14CCH to an integer. 
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CHAPTER 6 

Keyboard Input 


6.1 Single Character Input 

To input a single character from the keyboard, without posting it on the video display (essentially the 
INKEY$ function), execute a CALL 035BH. On return from this routine, the character is in the A register. If 
the A register contains zero, no character was entered. 

DISK SYSTEM CAUTION: The subroutine at 035BH has an exit (via RST 28H and RAM address 400CH) 
to DISK BASIC. This exit is taken only if the keyboard entry was made with the BREAK key. To protect 
against this contingency, either be certain that DISK BASIC is in place when you use this routine, or have 
your assembly language program fill location 400CH with a RET (C9H) before calling this routine. 

A somewhat more primitive method for single character input, which is sometimes useful, is to examine the 
keyboard memory directly. The keyboard memory is not actually memory at all, but an area in which certain 
address lines are connected to the data lines by switch closures. It is possible to tell which keys are depressed 
by examining these "memory" addresses. In this manner it is possible to determine whether combinations of 
keys are depressed, and whether or not a key has been released. 

The following chart represents the keyboard memory. The horizontal rows are the address locations; the 
vertical column s are the data values. If the "A" key is depressed, for example, memory location 3801H will 
appear to have a value of 2; if both "A" and "B" are depressed, it will have the value 6. The locations with 
"XXX" are unused, and the location marked "PCL" is the location of the Electric Pencil control key. 
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6.2 Numeric Input 


The function of the assembly language program segment given below is to print "?" on the video screen at 
the current cursor position, to input a string of (supposedly) numeric characters from the keyboard - echoing 
each character to the screen - and to convert this string to a number in integer, single precision, or double 
precision format, as appropriate. Here is the coding: 


CALL 

1BB3H 

INC 

HL 

CALL 

0E6CH 


The output is in 4121H-4122H if it is an integer, in 4121H-4124H if it is single precision, or in 
411DH-4124H if it is double precision. The variable type (2, 4, or 8, respectively) is in 40AFH. 

NOTE 1: No checking of the input string is performed. Whatever is typed in will be converted to some sort of 
number. 

NOTE 2: If integer output is desired regardless of what is typed in, the above code may be followed by: 

CALL 0A7FH 

If this is done, a fatal error occurs if a number whose absolute value is larger than 32767 is entered from the 
keyboard. 

DISK SYSTEM CAUTION: The subroutine at 1BB3H has three exits to DISK BASIC, with transfer points 
at 400CH, 41AFH, and 41C1H. To use the routine safely, either be sure that DISK BASIC is in place, or have 
your assembly language program fill locations 400CH, 41AFH, and 41C1H with RET's (C9H) before calling 
this routine. In addition, this subroutine uses the keyboard buffer area whose starting address is stored in 
40A7H-40A8H. DISK BASIC maintains a usable keyboard buffer between its own program region and the 
beginning of the BASIC text area. However, if DISK BASIC is absent, the locations 40A7H-40A8H may 
contain an unusable address. It follows that, if DISK BASIC cannot be guaranteed, your assembly language 
program should - before using the subroutine at 1BB3H - assign a keyboard buffer area (either within its own 
memory limits or in high RAM) by storing a starting address for this buffer in 40A7H-40A8H. 

6.3 Consistency Checked Numeric Input 

(a) The function of the routine to be given below is to print a query (followed by a "?") on the video screen at 
the current cursor position, to input a string of (supposedly) numeric characters from the keyboard - echoing 
each character to the screen - and to convert this string to a number in the specified format. If the string is 
inconsistent (containing a nonnumeric character other than a single decimal point, for example), the routine 
will print "? REDO" on the screen, and will then repeat the query and accept a new input string. (This cycle 
will be repeated until the input string is consistent.) 

SETUP: The query (but not the "?") and a variable name have to be set up somewhere in your assembly 
language program. Let's suppose that we want to input a number in single precision format, and that we shall 
call it AV!. (The "!" may not be necessary unless a declaration statement in your BASIC program defines the 


- 22 - 



variable type of variables whose names begin with A as other than single precision.) Assume also that the 
query is to be "AVERAGE?". Let us set this up in memory locations starting at the (symbolic) address 
QUERY: 

QUERY DEFM '"AVERAGE" ;AV! ' 

DEFB 0 

(The quotes around the query, the semicolon after the query, and the zero byte following the ASCII bytes for 
the query and variable name are all essential for the proper operation of the routine below.) 

The following assembly language routine will accomplish the function described above, with the label 
QUERY corresponding to the label in the setup just given: 


RETRY LD HL,QUERY 

LD A,(HL) 

CALL 21C9H 

LD A,(HL) 

OR A 

JR NZ,RETRY 


The result (in the format specified implicitly by the variable name) will be in 4121H-4122H if an integer, 
4121H-4124H if single precision, or 411DH-4124H if double precision. 

NOTE 1: If your assembly language program is entered via a SYSTEM command (rather than through a USR 
call), it will need to initialize the stack pointer at some high core location. Otherwise, an OM error may occur 
in the above routine. (See Section 10.1.) 

NOTE 2: The above routine sets up the variable name, type, and value in the BASIC variable storage area, or 
replaces a value already there. If a comma is inadvertently entered from the keyboard, "EXTRA IGNORED" 
will appear on the screen, and the value stored in 4121H-4122H, 4121H-4124H, or 411DH-4124H will be 
destroyed; the correctly converted value (for the characters preceding the comma) will still appear in variable 
storage, however, and may be retrieved from there by use of the VARPTR routine described in Section 10.2. 
(The starting address of the BASIC variable storage area is contained in locations 40F9H-40FAH. Be sure that 
your assembly language program does not overlap this area if it uses the above routine.) 

NOTE 3: This routine is still subject to an OV error in at least two cases: (1) The specified format is integer, 
and a number whose absolute value is larger than 32767 is entered, or, (2) The specified format is single or 
double precision, and the typist enters a number in E format with an exponent that is too large in absolute 
value. 

DISK SYSTEM CAUTION: Since the subroutine at 21C9H calls the subroutine at 1BB3H, the DISK 
SYSTEM CAUTION of Section 6.2 applies. (If DISK BASIC cannot be guaranteed, put RET's in 400CH, 
41AFH, and 41C1H, and assign a keyboard buffer area by storing its starting address in 40A7H-40A8H.) In 
addition, the subroutine at 21C9H has five more RAM transfer points to DISK BASIC, which should also be 
filled with RET's if DISK BASIC may not be in place when the subroutine is used. These other transfer points 
are: 41ACH, 41BEH, 41D0H, 41DCH, and 41DFH. 
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(b) In connection with the checking of numeric strings, there is another routine in the Level II ROM that is 
worth mentioning. This routine is activated by 

RST 10H 

and performs the following function: The character at the memory location one greater than that contained in 
the HL register pair is examined. If it is a space, the next character is examined; this loop is repeated until a 
character other than a space is found. The first character other than a space is then checked. If it is a digit 
(0-9), the C (carry) flag is set; otherwise, the C flag is turned off. Then, the routine returns control to the 
calling program with HL pointing to the checked character and the character itself in the A register. 


6.4 String Input 

(a) To display "?" on the video screen at the current cursor position, and then to input a string of up to 240 
characters, execute 


CALL 1BB3H 

The input string will be in consecutive memory locations starting at the address contained in 40A7H-40A8H, 
with a zero byte at the end. The HL register pair will contain an address one less than the starting address of 
the stored input. (See the DISK SYSTEM CAUTION of Section 6.2 regarding the use of this subroutine in 
disk systems.) 

(b) Here is a method of restricting the number of keyboard characters that will be accepted for input. If no 
more than n characters are to be allowed, use this assembly language program segment: 


LD 

HL,(40A7H) 

LD 

B, n 

CALL 

05D9H 


Up to n characters will be accepted, after which the keyboard will simply be ignored until the ENTER (or 
LEFT ARROW, or BREAK, or CLEAR) key is pressed. These characters will be stored in consecutive 
memory cells starting at the address contained in 40A7H-40A8H (the keyboard buffer area), with a ODH 
(carriage return) byte at the end. Upon completion, the HL register pair will contain the address of the first 
character of the stored input, and the B register will contain the number of characters entered. 


NOTE: No "?" is displayed as a result of the execution of the above program. If the "?" display is desired to 
prompt the typing of the input, precede the above program segment with: 


LD 

A, 3FH 

CALL 

033AH 

LD 

A, 20H 

CALL 

033AH 
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DISK SYSTEM CAUTION: If DISK BASIC may not be present when this routine is used, the keyboard 
buffer area should be assigned by storing an appropriate starting address in 40A7H-40A8H before executing 
the above code. Also, the subroutine at 05D9H has an exit to DISK BASIC with transfer point at 400CH, 
which should therefore be filled with a RET (C9H) if DISK BASIC may be missing when the subroutine is 
called. 


6.5 Intercepting the Keyboard Driver 

The ROM keyboard driver is a subroutine that scans the keyboard for input and decodes each character as it 
is entered. The entry point address of the ROM keyboard driver routine is 03E3H, and this is the address 
normally stored in the keyboard DCB at locations 4016H-4017H. By replacing the address in 4016H-4017H 
with the entry point address of your own assembly language program, you can either (1) substitute your own 
keyboard driver for that of the ROM, or (2) put your own keyboard pre-processing routine in front of the 
ROM's keyboard driver. (Various keyboard debounce programs operate on this second principle.) Thus, you 
can modify the interpretation of keyboard input to suit your particular requirements. A program that 
substitutes for the entire keyboard driver should end with a RET, while a program for pre-processing may end 
with a JP 03E3H. 
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CHAPTER 7 

Cassette Input-Output 


7.1 Tape On-Off, Leader, and Sync 

(a) To turn on the cassette, execute the following instructions: 

LD A, 0 

CALL 0212H 

(b) To write leader and sync byte: 

CALL 0287H 

(c) To search for leader and sync byte: 

CALL 0296H 

(d) To turn the cassette off: 

CALL 01F8H 


7.2 Single Character Input-Output 

(a) To write a character onto cassette tape (after the cassette has been turned on and leader and sync have 
been recorded), load the character into the A register and CALL 0264H. If more than one character is to be 
written, the CALL 0264H must be executed with sufficient frequency to sustain the 500 baud recording rate. 
The routine provides automatic timing. 

(b) To read a character from cassette (after the cassette has been turned on and leader and sync have been 
found), CALL 0235H. The input character will be in the A register. Again, the routine at 0235H must be called 
frequently enough to sustain the 500 baud rate if more than one character is to be read. 


7.3 CLOAD and CSAVE 

(a) Before CLOAD is called, the HL register pair should be loaded with the address of a zero byte, or the 
address of the first character of a string containing the program name, in quotes, followed by a zero byte. A 
B2H byte (a ROM code for "?") may (optionally) appear as the first character of this string if it is the tape 
verification function that is desired. The entry point of CLOAD is 2C1FH. CLOAD is not a closed subroutine. 
After 


CALL 2C1FH 
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control will not return to the calling program, but will pass instead to the Level 11 monitor. Since control is not 
returned to the calling program, a JP 2C1FH works as well as CALL 2C1FH. 

NOTE: If CLOAD is called (or jumped to) from an assembly language program that is itself entered via the 
SYSTEM command (rather than through a USR call), the stack pointer should first be initialized to a high 
RAM location. Otherwise, an OM error will occur, returning control to the Level II Monitor. (See Section 
10.1 for a fuller discussion of this point.) 

DISK SYSTEM NOTE: CLOAD probably has no usefulness in an assembly language program in a disk 
system. In any case, it should not be used in the absence of DISK BASIC, since it returns control to the Level 
II monitor, which has many exits to DISK BASIC. 

(b) CSAVE is a closed subroutine, as are all of the ROM routines that are described in this book, with the sole 
exception of CLOAD. Before CSAVE is called, the HL register pair should be loaded with the address of the 
first character of a string containing the program name, in quotes, followed by a zero byte. The entry point of 
CSAVE is 2BF5H. 


EXAMPLE: Suppose that it is desired to record a program named "S". (Only the first character of the name is 
put onto tape.) First, the name (in quotes), followed by a zero byte, has to be setup somewhere. This can be 
done symbolically as follows: 

PRGNAM DEFM '"S'" 

DEFB 0 

Then, execute these instructions: 


LD HL,PRGNAM 

CALL 2BF5H 


7.4 Tape Formats 

In this section four types of tapes are considered. These are: BASIC program tapes created with the CSAVE 
command, data tapes created by the BASIC statement "PRINT#-1", source code output from the TRS-80 
Editor/Assembler, and standard machine language tapes loaded with the SYSTEM command. All of these tape 
formats begin in the same way. This is with a leader of 256 bytes of zeroes, followed by a sync byte of A5H. 
After this, the formats diverge. 
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(a) BASIC Format 


Leader and sync byte 

D3H D3H D3H ;tape type identifier 

XX ;ASCII value of program name 


XX (LSB) 
XX (MSB) 
XX (LSB) 
XX (MSB) 
XX XX XX 
00 


;two byte address of NEXT 
; program line 
; 1 i ne number of PRESENT 
; program line 

;current line program text (compressed format) 
; zero 


(repeat above block until end) 

00 00 ;double zeroes indicate end of program 

Though the BASIC tape format includes specific addresses, the CLOAD subroutine will load programs 
originally saved in a system with different addresses. For example, BASIC programs saved in Level II will 
load into DISK BASIC even though the addresses are completely different. The format of BASIC program 
text in memory is exactly the same as the tape format, with the exception that the leader, tape type identifier, 
and file name are not stored. 


(b) PRINT#-1 Format 
Leader and sync byte 


XX XX XX... ;ASCII string 

2CH ;comma (see below) 


(repeat above block for each value) 

0DH ;end byte 

The data block is repeated, with a maximum number of 255 characters for each leader and sync byte. The 
last value is not, however, followed by a comma. If only one value or string is output, no comma appears at 
all. Numeric values are saved as ASCII strings with a leading and trailing space (20H). Because several 
seconds of time are taken to write each leader, data storage on cassette is very slow. The INPUT#-1 statement, 
however, does not usually need such a long leader. A substantial reduction of tape storage time can be 
accomplished by writing a custom machine language subroutine to write tape data with a short leader. (See 
Appendix 3.) 
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(c) Editor/Assembler Source Code Format 


Leader and sync byte 

D3H ;tape type identifier 

XX XX XX XX XX XX ;6 letter file name, padded with spaces (20H) 


XX XX XX XX XX 

5 digit ASCII line number with bit 7 set 

20H 

space 

XX XX XX... 

line text in ASCII 

0DH 

carriage return 

(repeat above block for each line) 

1 AH 

end of file marker 

(d) SYSTEM Tape Format 


Leader and sync byte 


55H 

tape type identifier 

XX XX XX XX XX XX 

6 letter file name, padded with spaces (20H) 

3CH 

block sync 

XX 

data length (0 represents 256) 

XX 

load address (LSB) 

XX 

load address (MSB) 

XX XX XX... 

data bytes 

XX 

checksum (sum of data and load address) 


(repeat above block for length of program) 


78H 

;block sync for 

end of file 

XX 

;execute address 

(LSB) 

XX 

;execute address 

(MSB) 
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CHAPTER 8 

Video Output 


8.1. Numeric Output 

To convert a number to a string of digits, and to display the latter on the video screen starting at the current 
cursor position, proceed as follows: 

(1) Store the number in 4121H-4122H (if it's an integer), or in 4121H-4124H (if it's single precision), or in 

411DH-4124H (if it's double precision). 

(2) Store the variable type (2, 4, or 8, respectively) in 40AFH. 

(3) CALL OFBDH. 

(4) CALL 28A7H. 

NOTE 1: The routine at OFBDH is the conversion routine described in Section 3.3 (a). The subroutine at 
28A7H is a general program for displaying a string of characters and updating the cursor position. The string 
to be displayed must be terminated by a zero byte, and the HL register pair must contain the address of the 
first character of the string before 28A7H is called. (The routine at OFBDH effects this setup automatically. 
See also Section 8.2 (b).) 

NOTE 2: Many of the ROM routines described in this book require a numeric input (or inputs). For most of 
these, the instructions given for calling them have not included the storage of the variable type flag in 40AFH. 
The reason is that, wherever possible, the variable type flag storage has been finessed by the choice of the 
subroutine entry point. In the routine of this section, that has not been possible, nor was it possible for the INT 
(Section 3.1 (b), the FIX (Section 3.1 (c)), the Number to Numeric String (Section 3.3 (a)), the SGN (Section 
5.8), or the ABS (Section 5.9) routines. Storing a 2, 4, or 8 in 40AFH takes only 5 bytes of machine code, but 
there are subroutines in the Level II ROM that can reduce the required code to 3 bytes. CALL 0A9DH will 
store a 2 in 40AFH. CALL OAEFH will store a 4 in 40AFH. And, finally, CALL OAECH will store an 8 in 
40AFH; this last subroutine, however, destroys the contents of the BC register pair. 

DISK SYSTEM CAUTION: The subroutine at 28A7H has two exits to DISK BASIC, with RAM transfer 
points at 41C1H and 41D0H. To use this routine safely, either be certain that DISK BASIC is in place or have 
your assembly language program fill locations 41C1H and 41D0H with RET's (C9H), before calling the 
routine. 


8.2 String Output 

(a) To print a single character at the current cursor position, and to update the cursor position, follow these 
steps: 

(1) Load the ASCII value of the character into the A register. 

(2) CALL 03 3AH. 

(b) To display a string of characters starting at the current cursor position, and to update the cursor position, 
proceed as follows: 

(1) Store the characters in consecutive memory locations, with a zero byte at the end. 

(2) Load the HL register pair with the address of the first character of the string. 

(3) CALL 28A7H. 
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EXAMPLE: Suppose that we have the following symbolic setup: 


TITL DEFM 

DEFB 


Then, the instructions 


LD 

CALL 


'INSIDE LEVEL II' 
0 


HL,TITL 
28A7H 


will cause "INSIDE LEVEL II" to be displayed at the current cursor position and the cursor position to be 
updated. 


NOTE: If the subroutine at 28A7H is used by an assembly language program that is itself entered by a USR 
call, the return from the assembly language program may encounter the embarrassment of a TM error, with 
control passing to the Level II monitor. This occurs because the subroutine at 28A7H leaves a 3 in location 
40AFH, while the USR structure requires a 2 in 40AFH upon returning. The malady is cured by storing a 2 in 
40AFH before returning, or by jumping to 0A9AH instead of executing the simple RET. The problem would 
not occur in the first place if the assembly language program returns the value of an integer variable to the 
BASIC program, and it might not occur if some other ROM routine is called after the subroutine at 28A7H 
and before returning - if the other subroutine produces an integer output. 


DISK SYSTEM CAUTION: See the DISK SYSTEM CAUTION of Section 8.1 regarding the exits to DISK 
BASIC from the subroutine at 28A7H. 
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CHAPTER 9 

Video Display Control 


9.1. CLS 

To clear the screen, CALL 01C9H. The cursor is reset to the home position, which is 3C00H. 


9,2 Tabbing 

To locate the cursor at position n on the current display line, where n is an integer between 0 and 3FH, 
inclusive, proceed as follows: 

(1) Load the E register with the value of n. 

(2) Load the HL register pair with the address of a zero byte in memory. 

(3) CALL 213FH. 

NOTE 1: The cursor position cannot be moved backward by this procedure. If n is not greater than the current 
cursor position on the line, no change will occur. 

NOTE 2: To locate the cursor at a given position on the screen (the function of the PRINT@ command in 
BASIC), the simplest procedure is to modify the cursor position bytes, which are located at 4020H-4021H. 
The address contained in these memory cells is that of the position in video memory (3C00H-3FFFH) at 
which the (abstract) cursor resides. This cursor position controls subsequent printing via the subroutine at 
28A7H, described in Section 8.2 (b). 

DISK SYSTEM CAUTION: The subroutine at 213FH has three exits to DISK BASIC, with RAM transfer 
points at 41BEH, 41C1H, and 41D3H. To use this routine safely, either be certain that DISK BASIC is in 
place, or have your assembly language program fill locations 41BEH, 41C1H, and 41D3H with RET's (C9H), 
before calling the routine. 


9.3 Scrolling 

To scroll (shift the entire display upward one line), CALL 0553H. 


9.4 Partial Clearing of Screen 

To clear the video screen from (including) position N - where N is an integer between 0 and 1023 
(decimal), inclusive - to the end of the display, proceed as follows: 

(1) Load the HL register with the value 3C00H + N. 

(2) CALL 057CH. 
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9.5 Special Display Functions 


Each of the special display functions listed below can be accomplished by the following procedure: 

(1) Load the A register with the value given below for the special function. 

(2) CALL 03 3AH. 

Here are the functions and their integer codes: 


(a) Backspace and erase previous character-08H 

(b) Carriage return and linefeed-ODH 

(c) Turn on cursor-OEH 

(d) Turn off cursor-OLH 

(e) Convert to 32 characters per line mode-17H 

(f) Backspace cursor-18H 

(g) Advance cursor one position-19H 

(h) Downward line feed- 1AH 

(i) Upward line feed---.1BH 

(j) Home (cursor to upper left comer)-1CH 

(k) Move cursor to beginning of current line-1DH 

(l) Erase from cursor position to end of line-1 EH 

(m) Erase from cursor position to end of screen-1FH 
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CHAPTER 10 

Miscellaneous Routines and Information 


10.1. Stack Pointer 

When an assembly language routine is entered via a USR call, the Z-80 stack pointer contains a high RAM 
address, because the Level II monitor sets up the stack in high RAM for its own purposes. Using this same 
stack area for your assembly language programs is a sound practice, whether your programs are in high core 
(above the stack, as intended by the designers of the TRS-80 software) or in low core (below the BASIC 
program, as will be recommended in Part II of this book.) 

However, if an assembly language routine is entered via a SYSTEM command, the stack pointer will be 
initialized to 4288H by the Level II monitor. The assembly language routine may then need to relocate the 
stack by loading the stack pointer with a high RAM address. This will be the case if the routine calls a ROM 
routine that checks for room in memory (CLOAD, or the routine described in Section 6.3 (a)), because the HL 
register pair is likely to contain an address higher than the stack - resulting in an OM error - unless the stack 
is moved to high core. 


10.2. VARPTR 

When used with a numeric variable as its argument, the VARPTR routine returns the address of the first 
byte of the value of that numeric variable. When used with a string variable as its argument, VARPTR returns 
the address of the first byte of a three-byte "dope" block that has the following structure: the first byte of this 
block contains the number of characters in the string, and the next two bytes of the block contain the address 
of the first character of the string. (See pages 8/8 and 8/9 of the Level II Basic Reference Manual.) These 
functions make VARPTR one of the most useful routines in ROM, because it helps us to link our assembly 
language and BASIC programs smoothly. (See Part II, especially Chapter 13.) 

To use VARPTR, we need to have set up in memory the name of the variable that we wish to reference, 
followed by a zero byte. Suppose, for example, that we want the address of the first byte of the value of the 
variable Al%. We might then use the following symbolic setup: 

VARNAM DEFM 'A1V 

DEFB 0 


To get our address, we execute these instructions: 

LD HL,VARNAM 

CALL 260DH 


Upon return, the DE register pair contains the desired address. If the variable has not yet been established by 
the BASIC program, the above procedure will set it up in BASIC variable storage (with a value of 0) and 
return the address of the first byte of its value. 
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If in the above example we change the setup to read 


VARNAM DEFM ’A1$' 

DEFB 0 


then the same machine language instructions given there will fetch (into the DE register pair) the address of 
the first byte of the three-byte "dope" block for the string variable Al$. 

The above examples involve a string variable and a simple numeric variable. How does one obtain the 
location of a numeric array variable? The easiest method to use is to secure the address of the first variable in 
the array and then to compute the address of that particular member of the array that is needed. The following 
facts must be kept in mind in order to carry out this procedure successfully. 

(1) The first member of an array is indexed by 0's. For example, if the array name is AR, then AR(0) is the 

first member if the array is one-dimensional, AR(0,0) is the first member if it is two-dimensional, 
etc. 

(2) The members of an array are stored in memory in order of increasing first index, then by increasing 

second index, then by increasing third index, etc. As an example, if the array AR is three- 
dimensional, with dimension numbers specified by DIM AR(2,1,1), then its 12 members are stored 
in memory in the following order (read across before descending): 


AR(0,0,0), AR( 1,0,0), AR(2,0,0), 

AR(0,1,0), AR( 1,1,0), AR(2,1,0), 

AR(0,0,1), AR( 1,0,1), AR(2,0,1), 

AR(0,1,1), AR(1,1,1), AR(2,1,1) 


(3) The spacing between successive members of an array in memory is the number of bytes required to 

represent each number in the array: 2 for an integer array, 4 for a single precision array, or 8 for a 
double precision array. 

(4) If the array is more than one-dimensional, then the assembly language routine needs to know the 

dimension numbers of the array. For the example above (AR with dimension numbers 2,1,1), the 
assembly language routine needs to know the 2 and the first 1 (which will be 3 and 2, respectively, 
in the calculations) in order to compute the addresses of the variables in the array. 

The following example should clarify the above points. 

EXAMPLE: Suppose that AR is a single precision array dimensioned by the BASIC statement DIM 
AR(5,3,2). Suppose that we want the address ofAR(2,2,l). First, the symbolic setup: 


ARNAM DEFM ’AR(0,0,0)' 

DEFB 0 


may be used to define the name of the first member of the array. Then, the instructions 


LD HL,ARNAM 

CALL 260DH 
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will fetch the address of AR(0,0,0) into the DE register pair. To this address must be added 4 x (2 + 2x6 + 
1x6x4). In this expression, the leftmost 4 is the number of bytes in the representation of a single precision 
variable, the 2, 2, 1 appearing inside the parentheses are the indices of the desired member of AR, the 6 (in 
both occurrences) is the range of the first index (0 to 5 covers 6 integral values), and the final 4 is the range of 
the second index. 


10.3 String Replacement 

After VARPTR has been used by an assembly language program to find a BASIC string variable, and after 
this string variable has been manipulated, there may arise the problem of replacing the variable in BASIC 
string variable storage. This problem seems particularly difficult if the modified string is longer than the 
original. In any case, the ROM routine described next may be used to effect the replacement. 

SETUP: The string should be held in a buffer area (preferably below the start of the BASIC text area as 
defined by the address in locations 40A4H-40A5H), with an uncommitted byte of memory in front of the 
string, and a zero byte at the end of the string. (The content of the uncommitted memory cell is immaterial.) 
Also, the name of the string needs to be set up somewhere with a zero byte at the end, as for example: 

VARNAM DEFM 'B$' 

DEFB 0 

Then, proceed as follows: 

(1) Load the HL register pair with the address of the uncommitted byte just preceding the first character of 

the string. 

(2) Load the BC register pair with the address of the first character of the variable name (VARNAM in the 

above setup). 

(3) CALL 21E3H. 

NOTE: If the string is held in a buffer area that is below the start of the BASIC text area as defined by the 
address in 40A4H-40A5H, then the string will be placed in BASIC string variable storage by the routine at 
21E3H. However, if the address of the string in its buffer area is higher than the starting address of the BASIC 
text area, then the string will not be moved at all; instead, its three-byte "dope" block will be adjusted to point 
to the string in its buffer area. It follows that you should not use a buffer area above the BASIC text area for 
the purpose of assembling a BASIC string unless you are willing to have that buffer area committed (that is, 
unusable for later operations on other strings.) 

DISK SYSTEM CAUTION: The subroutine at 21E3H has three exits to DISK BASIC, with RAM transfer 
points at 41BEH, 41DCH, and 41DFH. Either fill these locations with RET's (C9H), or be certain that DISK 
BASIC is in place before using this subroutine. 


10.4 LET 

The BASIC command LET (for assignment of variable values) is implemented by a subroutine with entry 
point at 1F21H. It is possible to use this subroutine in assembly language programs; simply follow these steps: 

(1) Load HL with the address of the first character of an appropriately modified assignment statement 

string that is terminated by a zero byte. 

(2) CALL 1F21H. 
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Examples of assignment statements are: 

(a) Z = SQR(X*X + Y*Y) 

(b) A$ = B$ + M1D$(C$,2,3) 

(c) E(I,J) = F(I,1)*G(1,J) + F(I,2)*G(2,J) 

By "appropriately modified assignment statement string" is meant a string consisting of the characters of an 
assignment statement in which the equals sign, each operator, and each function has been replaced by the one- 
byte code that the Level II ROM employs for that sign, operator, or function. Here is a complete list of these 
one-byte codes: 


+ 

CDH 

COS 

El H 

OR 

D3H 

- 

CEH 

CSNG 

F0H 

PEEK 

E5H 

* 

CFH 

EXP 

E0H 

POINT 

C6H 

/ 

D0H 

FIX 

F2H 

POS 

DCH 

t 

D1H 

FRE 

DAH 

RIGHTS 

F9H 

= 

D5H 

INKEYS 

C9H 

RND 

DEH 

ABS 

D9H 

INP 

DBH 

SGN 

D7H 

AND 

D2H 

INT 

D8H 

SIN 

E2H 

ASC 

F6H 

LEFTS 

F8H 

SQR 

DDH 

ATN 

E4H 

LEN 

F3H 

STR$ 

F4H 

CDBL 

FI H 

LOG 

DFH 

STRINGS 

C4H 

CHR$ 

F7H 

MEM 

C8H 

TAN 

E3H 

CINT 

EFH 

MID$ 

FAH 

VAL 

F5H 


The LET subroutine will fetch (from the BASIC storage area) the values of all the variables on the right 
side of the assignment statement, will perform the indicated calculations, and will return the result (to BASIC 
storage) as the value of the variable on the left side of the assignment statement. 

One significant use of the LET subroutine would be in a program that permits the entry of a function from 
the keyboard during execution, sets that function up as the right side of an assignment statement, and then 
calls the LET subroutine to evaluate the function. (Plotting and numerical integration programs are examples.) 
For this application it is helpful to have a subroutine that scans the assignment statement string, replacing the 
equality sign, each function, and each operator with its one-byte code as given in the table above. Such a 
routine exists in the ROM, with entry point at 1BC0H. The following code will modify an assignment 
statement string that has starting (symbolic) address ASSIGN (and that is terminated by a zero byte), will 
evaluate the right side of the assignment statement, and will store the result in BASIC variable storage as 
directed by the left side of the assignment statement: 


LD 

HL,ASSIGN 

CALL 

1BC0H 

INC 

HL 

CALL 

1F21H 


NOTE: The modified string will be assembled in the keyboard buffer area starting at the address that is 3 less 
than the address contained in 40A7H-40A8H. If DISK BASIC may not be present, your assembly language 
program should assign this buffer area by storing an appropriate address in 40A7H-40A8H before calling the 
subroutine at 1BC0H. 
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10.5 Output to Line Printer 

The entry point address of the line printer driver is 003BH. To output a character to the line printer, load the 
A register with the ASCII value of the character and CALL 003BH. 


10.6 POINT, SET, RESET 

These routines, whose functions are described on pages 8/1 and 8/2 of the Level II Basic Reference 
Manual, are activated in similar manner by the following procedure: 

(1) Load HL with the return address. 

(2) PUSH HL 

(3) Load the HL register pair with the address of a right parenthesis character in memory. 

(4) Load the A register with an identifier: 0 for POINT, 1 for RESET, or 80H for SET. 

(5) PUSH AF 

(6) Load A with the value of the X coordinate (an integer between 0 and 7FH, inclusive). 

(7) PUSH AF 

(8) Load A with the value of the Y coordinate (an integer between 0 and 2FH, inclusive.) 

(9) JP0150H 

If the function is POINT, upon return the desired indicator (0 if (X,Y) is off, -1 if it is on) will be in 
4121H-4122H. 


10.7 RUN 

To RUN a BASIC program, starting with its first line, execute the following instructions: 


LD 

HL,1D1EH 

PUSH 

HL 

JP 

1B5DH 


The ability to RUN a BASIC program from an assembly language program is valuable for linking the two 
programs, as will be shown in Part II. (See especially Chapter 14.) 


10.8 Re-entry to Level II Monitor 

The normal re-entry to the Level II Monitor is JP 1A19H. A jump to 0 will effect a complete restart 
(including the "MEMORY SIZE?" display in a diskless system). 
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PART II 


Linking Assembly Language and BASIC Programs 


CHAPTER 11 

Assemblers and Monitors 


Hand assembly of assembly language programs of more than a few dozen instructions is tedious, and the 
correcting of errors in such programs by hand reassembly is not to be recommended to your worst enemy. 
Obviously, to take full advantage of the information in this book you will need an assembly program. The 
TRS-80 Editor/Assembler (cassette version) is readily available, works well, and is easy to use. Recently a 
disk version of this assembler has been produced. Unfortunately, the cassette and disk versions differ 
somewhat in their notational conventions. The assembly language examples and listings in this book conform 
to the conventions of the cassette version of the TRS-80 Editor/Assembler. 

Another sort of program that is nearly essential in constructing and debugging assembly language programs 
is a machine language monitor. A number of monitors are currently available. The TRS-80 T-BUG monitor is 
rather primitive and has the serious flaw that it loads into low RAM, where it conflicts with the composite 
programs that are the subject of the remainder of this book. Other satisfactory monitors exist. Mumford Micro 
Systems offers a monitor named MicroMind that has been specially designed as a companion piece to this 
book. MicroMind incoiporates the following features: 

(1) It will run in any Level II 16K (or larger) system, with or without a disk. 

(2) It comes with a relocation program that enables its relocation to any convenient place in RAM. 

(3) It allows you to examine and change memory, examine and change the registers, set and restore break 
points, transfer control to any point in memory (including ROM), and record and verify SYSTEM tapes. 

(4) Assembly language programs can be executed one instruction at a time, with two full register displays - 
one before and one after the execution of each instruction. Any number of instructions (up to 255) can be 
executed at high speed by a special RUN command. Also, subroutines may be executed in full with a single 
command. 

(5) Ease of use has been a principal consideration in the design of MicroMind. For example, addresses may 
be entered in either decimal or hexadecimal without any awkward postfixes. Also, the flags are displayed, and 
can be examined and changed, individually, rather than as hard-to-remember bits in a general flag register. 

(6) MicroMind occupies only 2288 bytes of memory. 
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CHAPTER 12 

Relocating a BASIC Program 


When one writes a composite BASIC and assembly language program for the TRS-80, standard practice 
dictates that the BASIC program shall reside in low core, while the assembly language program shall occupy 
high core. There are two operational defects in this scheme: 

(1) Before the combined program can be loaded, the memory size must be set to accommodate the 

assembly language part. Otherwise, the BASIC program's string storage will overlap the assembly 
language area. 

(2) Loading the combined program involves two separate loading actions - a CLOAD and a SYSTEM 

load, if the programs are on tape. 

Defect (2) can be partially corrected in tape systems by loading the assembly language program first, then 
running it, whereupon it causes the BASIC program to be loaded by executing a CLOAD, as described in 
Section 7.3. The operator then has to perform only one loading action (a SYSTEM load), but he has to run 
twice - once from the SYSTEM state, and once from the READY (monitor) state, since CLOAD returns 
control to the monitor. For details of implementing this method, see the end of Chapter 14. 

An entirely different approach is possible. It is the purpose of the remainder of this book to show how to 
combine program sections so that the assembly language part resides in low core, the BASIC part is located 
immediately above this, and the two parts arc recorded on a single tape segment that can be loaded under the 
SYSTEM command and run from there (one load, one run). Besides eliminating the two defects mentioned 
above, this approach secures the superior features of the SYSTEM load (6-character titles and check sum 
testing) and also results in maximum compactness of the composite program in memory. 

A BASIC program is inherently relocatable. The reason that a CLOAD causes a BASIC program to be 
stored in memory starting at 42E9H (or considerably higher if you have an operating disk) is that locations 
40A4H-40A5H contain the address 42E9H (or higher, with a disk), and the monitor commences loading at the 
address contained in these locations. It follows that, if you were to change the address in 40A4H-40A5H to 
7000H, say, your BASIC programs would load starting at 7000H. They would load there, but they might not 
run correctly unless you had also taken care to store a zero byte in 6FFFH (in general, the location just before 
the starting load address). 

Now you know how to load a BASIC program into any part of RAM. This technique could be employed to 
load two separate BASIC programs into adjacent memory blocks, which would allow you to combine them 
into one program, provided that the second program has line numbers all of which are higher than any of the 
line numbers in the first program. However, to do this successfully, you obviously have to be able to learn 
where the first program ends. After a CLOAD, locations 40F9H-40FAH contain the address of the start of 
simple variable storage, which is just 3 bytes higher than the address of the last byte of the BASIC program. 
Thus, the following procedure permits combining two BASIC programs when the second has all higher line 
numbers than the first: 

(1) Load the first program via CLOAD. 

(2) PEEK at the address in 40F9H-40FAH, and store 2 less than this address in 40A4H-40A5H. 

(3) Load the second program via CLOAD. 

(4) Reset the address in 40A4H-40A5H to the value that it had prior to the first load. 
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From the above discussion it is apparent that locations 40F9H-40FAFI contain an address that is important 
for locating a BASIC program. Indeed, this is so. In order to RUN a BASIC program, it is essential not only 
that 40A4H-40A5H contain the starting address, but also that 40F9H-40FAH contain an address 3 larger than 
that of the final byte of the BASIC program. (RUN will initialize the contents of 40FBH-40FCH and 
40FDH-40FEH to agree with the address in 40F9H-40FAH, which explains why we need not be concerned 
with the locations 40FBH- 40FEH.) 

When we load a BASIC program via CLOAD, the ending address plus 3 is determined by the CLOAD 
program and stored in 40F9H-40FAH. Thus, under ordinary conditions, the address in 40A4H-40A5H is the 
only essential one for loading and running a BASIC program. 

But suppose that you sneak your BASIC program in through a SYSTEM load, as you are soon going to 
learn how to do. In this case, the addresses in 40A4H-40A5H and 40F9H-40FAH both become crucial. The 
assembly language program that precedes the BASIC program on the system tape will know where the 
BASIC program begins - namely, exactly one byte beyond where the assembly language program ends. (Note 
that it will be necessary to terminate the assembly language program with a zero byte.) Hence, it will know 
the correct address to store in 40A4H-40A5H. There is a subroutine in ROM that will find the end of a BASIC 
program if locations 40A4H-40A5H correctly tell it where the beginning is. Our assembly language program 
can use this routine to calculate the address to store in 40F9H-40FAH. The details will be given in Chapter 14. 
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CHAPTER 13 

Referencing BASIC Variables through VARPTR 


One of the main problems in linking separate programs is that of the passage of variables between them. 
The USR call allows a BASIC program to pass a single integer variable to an assembly language routine and 
to receive a single integer variable in return. (The assembly language routine receives its input in locations 
4121H-4122H and returns its output by loading it into HL and jumping to 0A9AH.) This, however, is too 
restrictive for general use. We need a method for passing variables back and forth on a more generous scale. 

The typical situation is that the assembly language routine needs several inputs from the BASIC program 
and that it returns several outputs to the BASIC program. This can be accomplished by using the VARPTR 
routine to find the addresses of the required BASIC variables and then employing these addresses either to 
fetch input variables or to store output variables. (Of course, one pair of integer variables can still be 
exchanged through the USR call.) The details of using VARPTR to find BASIC variable addresses have 
already been presented in Section 10.2. The following additional points should be clearly understood for 
successful variable passage by this method: 

(1) The assembly language routine needs to know the BASIC name and type (integer, string, single precision, 
or double precision) of each input and output variable that is not passed by the USR mechanism. For an array 
variable, the assembly language routine also needs to know the dimension numbers of the array. (You might 
compare this with FORTRAN subroutine linkage, in which the subroutine docs not need to know the name of 
a variable being passed, but does need to know the type, the dimension numbers for an array variable, and the 
position of the variable name in the parameter list of the calling program.) 

(2) For a numeric variable, VARPTR returns the address of the first byte of the value of the variable. For a 
string variable, however, VARPTR returns the beginning address of the 3-byte "dope" block of the string; the 
starting address of the string itself is contained in the last two bytes of this block. 

(3) Once the assembly language routine has obtained the address of a variable, it may save that address for 
later use - so long as that later use occurs before control is returned to the BASIC program. Saving such an 
address from one execution of the subroutine to the next could prove fatal, since the BASIC program may 
move its variables around in their storage area. Therefore, the assembly language routine should find the 
address again (through VARPTR) whenever it is re-entered. 

(4) To the BASIC program an assembly language subroutine will be essentially identical in appearance to a 
BASIC subroutine. The BASIC program knows that it needs to set up certain variables for the subroutine to 
operate upon, and it expects to find certain variable outputs when it regains control. The only difference is that 
one subroutine is activated by a USR call, while the other is activated by a GOSUB. 

(5) VARPTR will find the required address, but it is up to the assembly language program to fetch the (input) 
variable from that address, or to store the (output) variable at that address. This is merely a matter of 
transferring the correct number of bytes (for a numeric variable the number is 2, 4, or 8, depending upon 
variable type) as a block from one place in memory to another. The LDIR instruction can be helpful for 
moving more than 2 bytes. Also, the procedure explained in Section 10.3 can be used for returning string 
variables to the BASIC program. 
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CHAPTER 14 

The Linkage Initialization Segment 


In order to execute a combined BASIC and assembly language program, certain initializations must be 
performed at, or just prior to, run time. Here is a list of the required preliminary operations: 

(1) The entry point address of the assembly language processing routine must be stored in locations 

408EH-408FH in order to establish the linkage for the USR call. 

DISK SYSTEM NOTE: If you have a disk, the entry point address of the assembly language routine is 
ordinarily stored (by a DEFUSR command) in another location (in a table of such entry point addresses), from 
which it is transferred to 408EH-408FH at the time of execution of the USR call. In fact, DISK BASIC is 
quite intolerant of the storage of the entry point address in 408EH-408FH much before the subroutine is 
called. Therefore, readers with disk systems should not use the linkage initialization segment of this chapter. 
In Chapter 15 you will learn how to avoid the awkward DEFUSR command by keeping your own table of 
assembly language subroutine entry point addresses, from which the proper one will be transferred to 
408EH-408FH at the time of the USR call. 

(2) If the BASIC program is loaded into memory above the assembly language program (which is the 

technique recommended in this book), then the starting address for the BASIC segment must be 
stored in 40A4H-40A5H. 

(3) If the BASIC program is recorded together with the assembly language program and loaded via the 

SYSTEM command (as is also recommended), then the ending address (of the BASIC segment) 
plus 3 must be stored in 40F9H-40FAH. 

While operation (1) above could be performed in the BASIC segment of the program, and operations (2) 
and (3) could be performed manually, it is most efficient to have a special assembly language routine (which 
will be called the "linkage initialization segment") perform all three operations automatically. The advantage 
of automatic execution of (2) and (3) over manual execution is indisputable. As for operation (1), the 
assembly language routine knows (through the operation of assembly) the address of its own entry point, 
while the BASIC program could only be told this after the assembly of the assembly language part. Thus, a 
reassembly of the assembly language routine might necessitate a change in the BASIC program if the latter set 
up the address in 408EH-408FH by a POKE (or DEFUSR) command. 

The linkage initialization segment will be assembled and recorded just ahead of the assembly language 
processing routine, will be entered by running from the SYSTEM state, and will terminate by jumping to the 
RUN routine in ROM, causing the BASIC program to commence execution. Thus, the composite program can 
be loaded and executed in exactly the same manner as any machine language tape. 

The following annotated assembly language listing gives the details of the linkage initialization segment: 


ORG 

42E9H 

See 

NOTE 

1 

LD 

HL,ENTRY 

See 

NOTE 

2 

LD 

(408EH),HL 




LD 

HL,FINIS 

See 

NOTE 

3 

LD 

(40A4H),HL 




LD 

DE,65530 

See 

NOTE 

4 
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CALL 

1B2CH 

INC 

HL 

INC 

HL 

LD 

(40F9H),HL 

LD 

HL,1D1EH 

PUSH 

HL 

JP 

1B5DH 


See NOTE 5 


NOTE 1: The linkage initialization segment occupies the lowest available RAM. The origin of 42E9H is 
correct for a system with no disk. If you have a disk, do not use this linkage initialization segment - use the 
one in Chapter 15 instead. 

NOTE 2: The two instructions beginning with this line cause the entry point address (defined by the label 
"ENTRY") of the assembly language processing routine to be stored in 408EH-408FH, thus establishing the 
USR linkage. (The symbol "ENTRY" will, of course, appear somewhere as a label in the assembly language 
code that follows this initialization segment.) 

NOTE 3: The two instructions beginning with this line cause the starting address of the BASIC program 
segment to be stored in 40A4H-40A5H. "FINIS" is the symbolic name of the location immediately following 
the final byte of the assembly language program. The last three lines of your assembly language program 
should be as follows: 


DEFB 0 

FINIS DEFS 0 

END 

Observe the terminating zero byte, which must precede the BASIC program to follow. The DEFS 0 gives the 
label "FINIS" the correct address value without reserving any memory for it. 

NOTE 4: The five instructions beginning with this line store the address of the end of the BASIC program 
plus 3 in 40F9H-40FAH. The ROM routine at 1B2CH is the one (promised at the end of Chapter 12) that 
finds the end of the BASIC program. In order for the routine to do this, the beginning address of the BASIC 
program must be in 40A4H-40A5H, and the DE register pair must contain a line number larger than any in the 
BASIC program. These requirements have been satisfied by the three instructions preceding the CALL 
1B2CH. Upon return from this routine, the HL register pair contains the desired end address plus 1. The two 
INC HL instructions ensure that the proper address will be stored in 40F9H-40FAH. 

NOTE 5: The three instructions beginning with this line cause the BASIC program to be executed. (See 
Section 10.7.) 

If you decide not to follow the advice to locate your assembly language routines in low core, you may still 
want to incorporate a linkage initialization segment with the assembly language part of a composite program. 
In this case, the segment needs to perform only operation (1) given at the beginning of this chapter, and it 
might terminate by a jump to the CLOAD routine so that the BASIC program would be loaded automatically. 
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(The operating procedure would be a SYSTEM load, followed by a SYSTEM run, followed ultimately by a 
RUN from the READY state. The assembly language and BASIC programs would be recorded on separate 
but adjacent segments of the tape.) Here is a source listing for such an initialization segment for a diskless 
system: 



ORG 

7800H 

START 

LD 

HL,ENTRY 


LD 

(408EH),HL 


LD 

HL,ZBYT 


JP 

2C1FH 

ZBYT 

DEFB 

0 


The following notes are in explanation of the above listing: 

(1) The origin given is for illustration only. Choose the origin so that the assembly language routine will be 
located as high in memory as possible. (You need to know how long the assembly language program is before 
you can choose its best origin.) 

(2) The label "START" provides a reference address for the END statement of the assembly. Thus, the 
statement 

END START 

terminating the assembly language program will result in the object program's being recorded with an entry 
point address corresponding to START. 

(3) "ENTRY" is again the symbolic name of the entry point of the assembly language processing routine, 
which follows the linkage initialization segment. 

(4) As explained in Section 7.3 (a), the jump to 2C1FH - with HL pointing to a zero byte - effects a CLOAD 
of the BASIC program. 
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CHAPTER 15 

USR Call Expansion 


A large program may need more than one assembly language subroutine; but in a diskless system there is 
only one USR call. A way around this limitation is to index the subroutines and to activate the desired one by 
using its index as the argument for the USR call. (For example, X% = USR(3) would call subroutine 3.) The 
assembly language program would examine the argument passed by the USR call and transfer control to the 
indicated subroutine. 

Another possible solution to the problem - and the one apparently intended by the designers of the TRS-80 
software - is for the BASIC program to POKE (into 408EH-408FH) the address of each subroutine it needs 
just before calling it. But this is much too awkward, requiring, as it does, that the BASIC program know the 
memory address of every assembly language routine's entry point. 

If you have a disk, DISK BASIC provides 10 USR calls, which might seem to solve the problem. However, 
the efficient way to record the entry point addresses in the table of such addresses is for each assembly 
language routine to store its own, rather than for the BASIC program to do it with DEFUSR commands. (This 
is so because the use of DEFUSR commands would still require the BASIC program to know the entry point 
address of every assembly language subroutine.) But DISK BASIC's table of subroutine entry point addresses 
may have different locations in different versions of DOS. It follows that the use of DISK BASIC's USR 
augmentation does not provide the ideal solution. 

With or without a disk, it is easy to increase the number of available USR calls (to a maximum of 10) in a 
manner that is consistent with the linkage procedures recommended in this book. The method for doing this is 
to expand the linkage initialization segment as shown in the following annotated listing. 


ORG 

42E9H 

See NOTE 1 

LD 

A, 0C3H 

See NOTE 2 

LD 

(41A9H),A 


LD 

HL,USRENT 


LD 

(41AAH),HL 


LD 

HL,FINIS 


LD 

(40A4H),HL 


LD 

DE,65530 


CALL 

1B2CH 


INC 

HL 


INC 

HL 


LD 

(40F9H),HL 


LD 

HL,1D1EH 


PUSH 

HL 


JP 

1B5DH 


USRENT RST 

10H 

See NOTE 3 

JP 

NC,1997H 


PUSH 

HL 


SUB 

30H 


CP 

3 

See NOTE 4 

JP 

NC,1997H 


LD 

L, A 

See NOTE 5 
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LD 

H, 0 



ADD 

HL, HL 



LD 

DE,JPTBL 



ADD 

HL, DE 



LD 

E,(HL) 

See NOTE 


INC 

HL 



LD 

D,(HL) 



LD 

(408EH),DE 



POP 

HL 

See NOTE 


RET 



JPTBL 

DEFW 

ENTRY1 

Sec NOTE 


DCFW 

ENTRY2 



DEFW 

ENTRY3 



NOTE 1: The origin given is for a diskless system. If you have a disk, use a higher origin - 7000H is a good 
one. Observe that this linkage initialization segment is recommended for multiple USR calls even if you have 
a disk. This segment bypasses (and substitutes for) the USR augmentation of any disk system. (If you have a 
disk and need only one USR call, use the above segment with only one JPTBL entry.) Use of 7000H as the 
starting address for your assembly language routine in a system with a disk provides a margin of safety 
against future DOS enlargements and also allows you to record your program on disk with either a DUMP or 
TAPEDISK command. Once the program is on disk, it can be recalled by a LOAD command and can then be 
run by returning to BASIC and using the SYSTEM command. (It won't run immediately after a transfer to 
memory from disk, because the BASIC part of it requires the DISK BASIC overlay. However, if you have 
NEWDOS, the program can be loaded and executed directly from BASIC.) 

NOTE 2: The four instructions beginning with this line store a jump to USRENT in 41A9H-41ABH, causing 
the USR routine in ROM to call the routine above starting at USRENT. The next ten instructions in the above 
initialization segment are unchanged from Chapter 14. 

NOTE 3: The two instructions beginning with this line check for a syntax error. The "USR" command in your 
BASIC program must be followed immediately by a digit from 0 to 9. ("USR" without an ending digit is 
permitted in DISK BASIC in lieu of "USRO". The above augmentation does not permit "USR" without the 
terminating digit.) 

NOTE 4: The digit after the "USR" must not exceed one less than the number of entries in JPTBL. In this 
example there are three entries in JPTBL, and the digit is compared with 3. If there were 7 entries in JPTBL, 
the CP instruction would be CP 7. (A syntax error occurs if the digit following the "USR" is too large.) 

NOTE 5: The five instructions beginning with this line compute the address (within the JPTBL) at which the 
required entry point address is stored. 

NOTE 6: The four instructions beginning with this line transfer the entry point address of the desired 
subroutine from the JPTBL to locations 408EH-408FH. 

NOTE 7: The two instructions beginning with this line effect a graceful return to the USR routine in ROM. 
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NOTE 8: The JPTBL contains the (symbolic) entry point addresses of the several (three in this example) 
assembly language subroutines corresponding to the calls USRO, USR1, USR2, etc. The JPTBL addresses can 
be symbolic as long as all the subroutines and the linkage initialization segment are assembled together. When 
this is impracticable (perhaps due to memory limitation in using the Editor/Assembler), a somewhat more 
elaborate structure - to be explained in the next chapter - is required. 
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CHAPTER 16 

Linking Multiple Assembly Language Segments 


Suppose that you have written a combined BASIC and assembly language program that has several 
assembly language subroutines. In Chapter 15 you learned how to expand the number of USR calls so that the 
different subroutines would have different calls. If all the subroutines and the linkage initialization segment 
can be combined into one assembly, you have no further linkage problems. In a 16K machine the largest 
program that can be assembled by the TRS-80 Editor/Assembler is about 1000 bytes, and this estimate 
assumes that there are no space-consuming remarks. Now 1000 bytes are enough for most of the assembly 
language programs that you will write, but some of your programs may exceed this limit. In that case the 
assembly language subroutines may have to be assembled in two or more separate units, and there is then the 
problem of linking these units. 

A simple solution to this linkage problem involves dividing the linkage initialization segment among the 
several separate assemblies. Conceptually, the scheme works as follows: At run time, the first assembly is 
activated, and it stores a jump to the USR expansion routine in 41A9H-41ABH. Then control and a pointer to 
the second JPTBL location are passed to the second assembly, which stores its subroutine entry point address 
in the second JPTBL location. This daisy-chaining continues up to the last assembly, which stores its 
subroutine entry point address in the last JPTBL location, completes the linkage initialization procedure, and 
finally jumps to the RUN routine in ROM to cause the BASIC program to commence execution. 

There is one flaw in the above scheme: Each assembly language segment except the last must know the 
origin of the next segment in the chain. There is no obvious way to eliminate this flaw, but its effect can be 
minimized. After the assembly language segments have been written, determine their lengths and allow an 
extra 50 or so bytes for each one. Then, starting from origin 42E9H (or higher, with a disk), firm origins can 
be established for all of the segments. The resulting program will occupy slightly more memory than 
necessary, but you will gain two advantages: 

(1) Each segment will have its own space for patching during the debugging phase. 

(2) Each subroutine can be reassembled independently of all the others, provided that its reassembled 

length is not too much greater than its original length. 

The following annotated listing illustrates the linkage procedure for three assembly language segments. 


USRENT 



ASSEMBLY 1 

ORG 

42E9H 

LD 

A, 0C3H 

LD 

(41A9H),A 

LD 

HL,USRENT 

LD 

(41AAH),HL 

LD 

HL,JPTBL+2 

JP 

4600H 

RST 

10H 

JP 

NC,1997H 

PUSH 

HL 

SUB 

30H 


See NOTE 1 
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JPTBL 


CP 3 

JR NC,1997H 

LD L,A 

LD H, 0 

ADD HL,HL 

LD DE,JPTBL 

ADD HL,DE 

LD E,(HL) 

INC HL 

LD D,(HL) 

LD (408EH),DE 

POP HL 

RET 

DEFW ENTRY1 See NOTE 2 

DEFS 2 

DEFS 2 


ASSEMBLY 2 


ORG 

4600H 




LD 

BC,ENTRY2 

See 

NOTE 

3 

LD 

(HL),C 




INC 

HL 




LD 

(HL),B 




INC 

HL 

See 

NOTE 

4 

JP 

4900H 





ASSEMBLY 3 


ORG 

4900H 

LD 

BC,ENTRY3 

LD 

(HL),C 

INC 

HL 

LD 

(HL),B 

LD 

HL,FINIS 

LD 

(40A4H),HL 

LD 

DE,65530 

CALL 

1B2CH 

INC 

HL 

INC 

HL 

LD 

(40F9H),HL 

LD 

HL,1D1EH 

PUSH 

HL 

JP 

1B5DH 


See NOTE 5 


See NOTE 6 
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FINIS 


DEFB 

DEFS 

END 


0 

0 


See NOTE 7 


NOTE 1: The HL register pair is loaded with a pointer to the second JPTBL location; the correct value is 
JPTBL+2 because the addresses stored in JPTBL each occupy 2 bytes. The JP 4600H instruction in the next 
line presupposes that the second assembly language segment begins at 4600H. (In practice the correct address 
here is determined by finding the length of the first segment, padding it a bit, and adding the total to the origin 
of the first segment.) 

NOTE 2: The JPTBL already contains the (symbolic) entry point address of the subroutine in the first 
assembly language segment. The entry point addresses of the subroutines in the later segments will be stored 
in the table by those segments. The table has just enough room for those addresses. 

NOTE 3: The four instructions beginning with this line store the entry point address of the subroutine in the 
second assembly language segment at the second JPTBL location, which is pointed to by the HL register pair. 
(Compare with NOTE 1.) 

NOTE 4: HL is incremented so that it points to the third location in the JPTBL. Control then passes to the 
third assembly language segment at 4900H. 

NOTE 5: The four instructions beginning with this line store the entry point address of the subroutine in the 
third assembly language segment at the third JPTBL location. 

NOTE 6: The ten instructions beginning with this line complete the linkage initialization procedure, 
culminating in a jump to RUN. (Compare with the listings of Chapters 14 and 15.) 

NOTE 7: Again we see the mandatory zero byte just before the BASIC program. 

If you have a disk, the above sample listing needs to be changed in only two respects: 

(1) The origins of the three assemblies would be higher. 

(2) In each of the first two assemblies the jump to the origin of the next assembly would have to be 
modified to conform to the higher origin of the next assembly. 

Observe once more that it is recommended that you use the above linkage procedure either with or without a 
disk. If you have a disk, the given USR expansion substitutes for the USR augmentation of DISK BASIC. 


With this recommended structure, it also becomes possible for any of your assembly language subroutines 
to call an assembly language subroutine in any other segment. The following annotated listing shows how this 
can be done. 
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LD 

HL,SRNUM-1 

CALL 

41A9H 

LD 

HL,(ARG) 

LD 

(4121H),HL 

CALL 

2815H 


SRNUM DEFB '2' 


See NOTE 8 


See NOTE 9 


NOTE 8: The two instructions beginning with this line are used to pass an integer argument - assumed to be 
stored in two bytes starting at the symbolic address ARG - to the subroutine being called. If no argument is to 
be passed, these instructions may be omitted. If the called subroutine ordinarily returns an integer value 
through the USR mechanism, that value will be found in 4121H-4122H and in HL. 

NOTE 9: The setup at symbolic address SRNUM (for "subroutine number") is for calling the subroutine that 
the BASIC program would call by USR2. For the subroutine called by USR5, the byte defined here should be 
'5', etc. 
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CHAPTER 17 

Taping, Loading, and Executing Composite Programs 


Let us assume that you have written a composite program using the linkage methods that have been 
described in the preceding chapters. Here are the steps to follow in putting it all together. 

(1) Assemble and debug each assembly language segment separately and record the object code. Make a note 
of the address of the "FINIS" label in the final segment. 

(2) Write, debug, and record the BASIC program segment. 

(3) Load all the assembly language segments into memory via the SYSTEM command. Also, load a machine 
language monitor with SYSTEM recording capability (such as MicroMind) into the high end of memory. 

(4) POKE the ending address plus 1 of the last assembly language segment into 40A4H-40A5H. (Or use the 
machine language monitor to do it. Thi s address is that of the "FINIS" label, saved from step (1).) 

(5) Load the BASIC program via the CLOAD command. 

(6) Use the machine language monitor to record the composite program on tape. The starting address for this 
recording will be the origin of the first assembly language segment, the ending address will be the address that 
you find in 40F9H-40FAH, and the entry point address will also be the origin of the first assembly language 
segment. Give your program whatever name you choose. 

Now you have your composite program recorded as a single segment on tape in a SYSTEM compatible 
format. To load and execute this tape, use the SYSTEM command, type the name of your program, and press 
ENTER. When the tape has been loaded, type "/" and press ENTER. 

What if you discover errors in your program now? If an error is found in the BASIC segment, correction 
the usual way. (You will find that the BASIC program can be LISTed and EDITed as usual after the composite 
program has been run once. Do not try to LIST before running the composite program.) Then record the entire 
program again with the machine language monitor, using the new address in 40F9H-40FAH as the ending 
address. 

DISK SYSTEM NOTE: With TRS-DOS, editing of a composite program may occasionally result in 
"INTERNAL ERROR" and a reinitialization of DOS. This sporadic error seems to depend upon the location 
in memory of the line being edited. If a particular edit seems to be impossible to accomplish in the composite 
program, perform it on the separate BASIC program segment and then retape the entire program. 

If an error is discovered in an assembly language segment, it can be patched, provided that you have left 
some room at the end of the segment for this purpose. Then record the entire program again. Or, if you wish, 
this segment can be reassembled without modifying any of the other segments, as long as its new length does 
not exceed the original space allocation for the segment. In case of a reassembly, reload the composite 
program, then load the new assembly and retape the entire program. (Note that the final segment can be 
reassembled at will, since an increased length for it will merely cause a relocation of the BASIC segment 
without affecting any of the linkages. Of course, to retape after such a reassembly would require reloading the 
composite program, followed by the reassembled final assembly language segment and the BASIC segment.) 
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Modifications or augmentations of any of the segments can be handled exactly like errors. However, if an 
augmentation of any assembly language segment except the last one causes that segment to exceed its original 
space allocation, then all subsequent assembly language segments will have to be reassembled with new 
origins. (Nothing changes in any of these segments except their origins and the forward jump addresses in 
their linkage initialization segments.) 

As has been mentioned above, once the composite program has been run from the SYSTEM state, the 
BASIC program can be both LISTed and EDITed. It can also be RUN, which means that it is unnecessary to 
reenter the SYSTEM state to rerun the composite program. (The linkage initialization segments need to 
perform their function only once - when the program is first loaded.) 

If you have a disk, the composite program can be loaded via the SYSTEM command and then saved on 
disk by a DUMP, provided that you have given its first segment an origin of 7000H or higher. Once the 
program is on disk, it can be recalled by a LOAD and can be run by returning to BASIC and using the 
SYSTEM command. (It won't run immediately after a transfer to memory from disk, because the BASIC part 
of it requires the DISK BASIC overlay. However, if you have NEWDOS, the program can be loaded and 
executed directly from BASIC.) 

DISK SYSTEM NOTE: The DISK SYSTEM CAUTlONs of Part I of this book detailed the special 
precautions that must be taken in using some of the ROM subroutines in assembly language programs that 
may be executed in the absence of the DISK BASIC overlay. Since the composite programs of Part II require 
the presence of DISK BASIC, all the ROM subroutines of Part I may be used in these composite programs 
without any special precautions. 
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CHAPTER 18 

An Example of a Composite Program 


In this final chapter is given an example of a complete program constructed with the techniques explained 
in this book. The program computes any positive (integral) power up to the 500th of any positive integer up to 
7392 and displays all the digits. Input is processed by the BASIC program segment, while the calculations are 
done in assembly language for maximum speed. (As an example, 137 to the power of 20 is computed in about 
half a second by this program, while an equivalent all-BASIC program would take about 20 seconds for the 
same calculation.) Output of the multi-digit result is also done in an assembly language subroutine; this 
feature is not absolutely necessary for speed of execution but has been included to illustrate the linkage of two 
separate assembly language routines to a BASIC program. 

In studying this example, pay particular attention to the linkage initialization segments, the USR call 
expansion, and the use of VARPTR and the USR calls themselves to pass variables between the BASIC and 
assembly language programs. Here is the annotated listing: 

ASSEMBLY 1 


00100 


ORG 

42E9H 




00110 


LD 

A.0C3H 




00120 


LD 

(41A9H),A 




00130 


LD 

HL,USRENT 




00140 


LD 

(41AAH),HL 




00150 


LD 

HL,J PTBL+2 




00160 


JP 

4400H 

; See 

NOTE 

1 

00170 

USRENT 

RST 

10H 




00180 


JP 

NC,1997H 




00190 


PUSH 

HL 




00200 


SUB 

30H 




00210 


CP 

2 




00220 


JP 

NC,1997H 




00210 


LD 

L , A 




00240 


LD 

H , 0 




00250 


ADD 

HL , HL 




00260 


LD 

DE,JPTBL 




00270 


ADD 

HL , DE 




00280 


LD 

E,(HL) 




00290 


INC 

HL 




00300 


LD 

D,(HL) 




40310 


LD 

(408EH),DE 




00320 


POP 

HL 




00330 


RET 





00340 

JPTBL 

DEFW 

ENTRY1 




00350 


DEFS 

2 




00360 

ENTRY1 

LD 

HL,(4121H) 

; See 

NOTE 

2 

00370 


LD 

(NHLD),HL 




00380 


LD 

HL.ENAM 

; See 

NOTE 

3 

00390 


CALL 

260DH 




00400 


EX 

DE , HL 




00410 


LD 

E,(HL) 




00420 


INC 

HL 




00430 


LD 

D,(HL) 




00440 


LD 

(EHLD),DE 




00450 


LD 

HL,PWNAM 




00460 


CALL 

260DH 




00470 


LD 

(PWPNT),DE 




00480 


LD 

HL , -1 




00490 


LD 

(DHLD),HL 




00500 


LD 

DE,(NHLD) 




00510 


CALL 

SPREAD 

; See 

NOTE 

4 
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00520 


LD 

BC, 1 




00530 

L00P1 

PUSH 

BC 

; See 

NOTE 

5 

00540 


LD 

BC, 0 




00550 


LD 

D, B 




00560 


LD 

E , C 




00570 

LOOP2 

PUSH 

BC 




00580 


LD 

HL,(PWPNT) 




00590 


ADD 

HL.BC 




00600 


LD 

(PWIND),HL 




00610 


LD 

B, (HL) 




00620 


PUSH 

DE 




00630 


LD 

DE,(NHLD) 




00640 


LD 

HL , 0 




00650 


LD 

A, B 




00660 


OR 

A 




00670 


JR 

Z , OUT 




00680 

LOOP3 

ADD 

HL , DE 

; See 

NOTE 

6 

00690 


DJNZ 

LOOP3 




00700 

OUT 

POP 

BC 




00710 


ADD 

HL , BC 




00720 


CALL 

DIVID 

; See 

NOTE 

7 

00730 


LD 

A, H 




00740 


LD 

HL,(PWIND) 




00750 


LD 

(HL) ,A 




00760 


POP 

BC 




00770 


LD 

HL,(DHLD) 




00780 


OR 

A 




00790 


SBC 

HL.BC 




00800 


INC 

BC 




00810 


JR 

NZ.LOOP2 




00820 


CALL 

SPREAD 

; See 

NOTE 

4 

00830 


POP 

BC 




00840 


INC 

BC 




00850 


LD 

HL, (EHLD) 




00860 


OR 

A 




00870 


SBC 

HL.BC 




00880 


JR 

NZ.LOOP1 




00890 


LD 

HL,(DHLD) 

; See 

NOTE 

8 

00900 


JP 

0A9AH 




00910 

SPREAD 

LD 

A, D 

; See 

NOTE 

4 

00920 


OR 

E 




00930 


RET 

Z 




00940 


EX 

DE , HL 




00950 


CALL 

DIVID 

; See 

NOTE 

7 

00960 


LD 

A, H 




00970 


LD 

HL,(DHLD) 




00980 


INC 

HL 




00990 


LD 

(DHLD),HL 




01000 


LD 

BC,(PWPNT) 




01010 


ADD 

HL.BC 




01020 


LD 

(HL) ,A 




01030 


JR 

SPREAD 




01040 

DIVID 

LD 

DE ,0 

; See 

NOTE 

7 

01050 


LD 

C,10 




01060 


LD 

A, H 




01070 


DEC 

D 




01080 

L00P4 

INC 

D 




01090 


SUB 

C 




01100 


JR 

NC.L00P4 




01110 


ADD 

A, C 




01120 


LD 

H , A 




01130 


LD 

B, 8 




01140 

LOOP5 

ADD 

HL , HL 




01150 


RLC 

E 




01160 


LD 

A, H 




01170 


SUB 

C 




01180 


JR 

C , NIX 




01190 


LD 

H , A 




01200 


INC 

E 
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L00P5 


01210 

NIX 

01220 


01230 

EHLD 

01240 

PWPNT 

01250 

DHLD 

01260 

NHLD 

01270 

PWIND 

01280 

ENAM 

01290 


01300 

PWNAM 

01310 


01320 



DJNZ 
RET 
DEFS 2 

DEFS 2 

DEFS 2 

DEFS 2 

DEFS 2 

DEFB 1 E 1 

DEFB 0 

DEFM 1 PW(0) 

DEFB 0 

END 


NOTE 1: 4400H is the origin of Assembly 2. (If you have a disk, both assemblies would have higher origins.) 
It was chosen so as to leave about 50 bytes of free memory at the end of Assembly 1. When Assembly 1 was 
being debugged, this free space proved valuable for patching. 

NOTE 2: The two instructions beginning with this line retrieve the value of the integer variable N (passed by 
the USRO call in the BASIC program) and store it locally at NHLD. 

NOTE 3: The ten instructions beginning with this line use VARPTR twice to (1) fetch the value of the BASIC 
variable E and store it locally at EHLD, and (2) fetch the beginning address of the (BASIC) PW array and 
store it locally at PWPNT. 

NOTE 4: SPREAD is the entry point of a subroutine that separates the digits of the integer in the DE register 
pair and stores these digits in separate bytes of the PW array. 

NOTE 5: The 36 instructions beginning with this line form a nest of three loops that multiply N by itself (digit 
by digit) E-l times and store the digits in the PW array. Observe the use of the stack (the PUSHes and POPs) 
for efficient handling of the loop counters for loops 1 and 2. 

NOTE 6: The two-instruction loop beginning with this line performs a fast multiplication of the integer N by 
the digit in the B register. 

NOTE 7: DIVID is the entry point of a subroutine that performs a fast division by 10. The dividend is passed 
to the subroutine in the HL register pair, and the quotient and remainder are returned in the DE and A 
registers, respectively. 

NOTE 8: The two instructions beginning with this line effect a return to the BASIC program and the passage 
of the value of the integer variable D to that program. (The value of D is one less than the number of digits in 
N to the power of E.) 
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ASSEMBLY 2 


00100 


ORG 

4400H 




00110 


LD 

BC,ENTRY2 




00120 


LD 

(HL) ,C 




00130 


INC 

HL 




00140 


LD 

(HL) ,8 




00150 


LD 

HL , FINIS 




00160 


LD 

(40A4H),HL 




00170 


LD 

DE,65530 




00180 


CALL 

1B2CH 




00190 


INC 

HL 




00200 


INC 

HL 




00210 


LD 

(40F9H),HL 




00220 


LD 

HL,1D1EH 




00230 


PUSH 

HL 




00240 


JP 

1B5DH 




00250 

ENTRY2 

LD 

HL,(4121H) 

; See 

NOTE 

9 

00260 


PUSH 

HL 




00270 


LD 

HL,PWNAM 

; See 

NOTE 

10 

00280 


CALL 

260DH 




00290 


LD 

(PWPNT),DE 




00300 


POP 

DE 

; See 

NOTE 

11 

00310 

LOOP 

PUSH 

DE 

; See 

NOTE 

12 

00320 


LD 

HL,(PWPNT) 




00330 


ADD 

HL , DE 




00340 


LD 

A,(HL) 




00350 


ADD 

A, 30H 




00360 


LD 

HL,STROUT 




00370 


LD 

(HL) ,A 




00380 


CALL 

28A7H 




00390 


POP 

DE 




00400 


LD 

A, 0 




00410 


OR 

E 




00420 


JP 

Z.0A9AH 

; See 

NOTE 

13 

00430 


DEC 

DE 




00440 


JR 

LOOP 




004S0 

PWNAM 

DEFM 

'PW(0) 1 




00460 


DEFB 

0 




00470 

PWPNT 

DEFS 

2 




00480 

STROUT 

DEFS 

1 




00490 


DEFB 

0 




00500 


DEFS 

50 




00510 


DEFB 

0 




00520 

FINIS 

DEFS 

0 




00530 


END 






NOTE 9: The two instructions beginning with this line retrieve the value of the integer variable D (passed by 
the USR1 call in the BASIC program) and store it on the stack. 


NOTE 10: The three instructions beginning with this line fetch the starting address of the PW array (using 
VARPTR) and store it locally at PWPNT. 


NOTE 11: Here the value of D is retrieved from the stack. (See NOTE 9.) 


NOTE 12: The 14 instructions beginning with this line form a loop that prints the digits in the PW array. The 
digits are fetched from the PW array one at a time - starting with the high end, and proceeding to the low end 
of the array - and are printed individually by the ROM routine at 28A7H. (See Section 8.2 (b).) 


NOTE 13: When all the digits have been printed, control returns to the BASIC program. The instruction JP 
Z,0A9AH is used rather than RET Z because the routine at 28A7H leaves a 3 in 40AFH. (See Section 8.2 (b).) 
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BASIC SEGMENT 


100 DEFINT A-Z:DIM PW(1000) 

110 CLS 

120 PRINT "A PROGRAM TO RAISE NUMBERS TO POWERS 

130 PRINT:INPUT "NUMBER";N 

140 IF N>0 AND N<7393 THEN 160 

150 PRINT "ILLEGAL NUMBER":GOTO 130 

160 INPUT "POWER";E 

170 IF E>0 AND E<501 THEN 190 

180 PRINT "ILLEGAL POWER":GOTO 160 

190 IF E=1 THEN 210 

200 D=USR0(N) 

210 PRINT 

220 PRINT N;"TO THE POWER OF";E;"IS:" 

230 PRINT 

240 IF E=1 THEN 280 
250 X=USR1(D) 

260 PRINT:PRINT:INPUT AS 
270 CLS:GOTO 130 
280 PRINT N:GOTO 260 
290 END 
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APPENDIX 1 

Hex-Decimal Conversion Table 


The table which follows is a useful tool for converting numbers between base 10 (decimal) and base 16 
(hexadecimal). This ability is often required in programming. The table consists of 12 columns of numbers, in 
4 groups of three. Within each group of three, the first column is a single byte hexadecimal value. The second 
column is the high order decimal equivalent of the hex byte, and the third column is the low order decimal 
equivalent of the hex byte. 

To convert a single byte hex value to decimal, just find the 2 digit hex value in the first column and read its 
equivalent in the third column. 

EXAMPLE: To convert AFH to decimal, find it in the first column. It corresponds to 175 in the third column. 

To convert a 4 digit hex number to decimal, find the 2 digit high order byte in the first column. Its decimal 
value is shown in the middle column. Write this number down. Now find the 2 digit low order byte in the first 
column and read its decimal equivalent in the third column. The sum of these two decimal numbers is the 
decimal value of the two byte hexadecimal number. 

EXAMPLE: To convert 1A19H to decimal, find 1A in the first column. It corresponds to 6656 in the middle 
column. Then find 19 in the first column and its equivalent in the third column, 25. 1A19H is the 
same as 6656 + 25 or 6681 (decimal). 

To convert a decimal number smaller than 256 to hex, find it in the third column. The hexadecimal 
equivalent will be found in the first column. If the decimal number is larger than 256, find the largest decimal 
number in the middle column which is smaller than or equal to the number in question. The corresponding 
hexadecimal byte in the first column is the high order hex value of the decimal number. Now find the 
difference between this decimal number and the original one. The hex value corresponding to this number 
(which should be less than 256) is the low order byte of the hex equivalent. 

EXAMPLE: To convert 16429 to hexadecimal notation, find 16384 in the middle row. It is smaller than 
16429, and the next number in the middle row is larger than 16429. The hexadecimal equivalent of 
16384 is 40, and this is the high order half of the hex number. Now subtract 16384 from 16429. The 
difference is 45, which corresponds to a hex value of 2D. The hexadecimal equivalent of 16429 is 
therefore 402DH. 

The high order values of the four major groups of three columns can be seen to correspond to the 16K 
increments of the TRS-80 computer memory. The first group (from 0 to 3F00H) represents the ROM, 
keyboard, and video areas. The second group represents the extent of a 16K machine and the third group a 
32K machine. A 48K machine contains memory in all locations shown on this table. This visualization is 
sometimes useful in understanding the positioning of programs and hardware in the TRS-80. 
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Hex-Decimal Conversion Table 


HEX 

DECIMAL 

HEX 

DECIMAL 

HEX 

DECIMAL 

HEX 

DECIMAL 

00 

0 

0 

40 

16384 

64 

80 

32768 

128 

C0 

49152 

192 

01 

256 

1 

41 

16640 

65 

81 

33024 

129 

Cl 

49408 

193 

02 

512 

2 

42 

16896 

66 

82 

33280 

130 

C2 

49664 

194 

03 

768 

3 

43 

17152 

67 

83 

33536 

131 

C3 

49920 

195 

04 

1024 

4 

44 

17408 

68 

84 

33792 

132 

C4 

50176 

196 

05 

1280 

5 

45 

17664 

69 

85 

34048 

133 

C5 

50432 

197 

06 

1536 

6 

46 

17920 

70 

86 

34304 

134 

C6 

50688 

198 

07 

1792 

7 

47 

18176 

71 

87 

34560 

135 

C7 

50944 

199 

08 

2048 

8 

48 

18432 

72 

88 

34816 

136 

C8 

51200 

200 

09 

2304 

9 

49 

18688 

73 

89 

35072 

137 

C9 

51456 

201 

0A 

2560 

10 

4A 

18944 

74 

8A 

35328 

138 

CA 

51712 

202 

0B 

2816 

11 

4B 

19200 

75 

8B 

35584 

139 

CB 

51968 

203 

0C 

3072 

12 

4C 

19456 

76 

8C 

35840 

140 

CC 

52224 

204 

0D 

3328 

13 

4D 

19712 

77 

8D 

36096 

141 

CD 

52480 

205 

0E 

3584 

14 

4E 

19968 

78 

8E 

36352 

142 

CE 

52736 

206 

0F 

3840 

15 

4F 

20224 

79 

8F 

36608 

143 

CF 

52992 

207 

10 

4096 

16 

50 

20480 

80 

90 

36864 

144 

D0 

53248 

208 

11 

4352 

17 

51 

20736 

81 

91 

37120 

145 

D1 

53504 

209 

12 

4608 

18 

52 

20992 

82 

92 

37376 

146 

D2 

53760 

210 

13 

4864 

19 

53 

21248 

83 

93 

37632 

147 

D3 

54016 

211 

14 

5120 

20 

54 

21504 

84 

94 

37888 

148 

D4 

54272 

212 

15 

5376 

21 

55 

21760 

85 

95 

38144 

149 

D5 

54528 

213 

16 

5632 

22 

56 

22016 

86 

96 

38400 

150 

D6 

54784 

214 

17 

5888 

23 

57 

22272 

87 

97 

38656 

151 

D7 

55040 

215 

18 

6144 

24 

58 

22528 

88 

98 

38912 

152 

D8 

55296 

216 

19 

6400 

25 

59 

22784 

89 

99 

39168 

153 

D9 

55552 

217 

1A 

6656 

26 

5A 

23040 

90 

9A 

39424 

154 

DA 

55808 

218 

IB 

6912 

27 

5B 

23296 

91 

9B 

39680 

155 

DB 

56064 

219 

1C 

7168 

28 

5C 

23552 

92 

9C 

39936 

156 

DC 

56320 

220 

ID 

7424 

29 

5D 

23808 

93 

9D 

40192 

157 

DD 

56576 

221 

IE 

7680 

30 

5E 

24064 

94 

9E 

40448 

158 

DE 

56832 

222 

IF 

7936 

31 

5F 

24320 

95 

9F 

40704 

159 

DF 

57088 

223 

20 

8192 

32 

60 

24576 

96 

A0 

40960 

160 

E0 

57344 

224 

21 

8448 

33 

61 

24832 

97 

A1 

41216 

161 

El 

57600 

225 

22 

8704 

34 

62 

25088 

98 

A2 

41472 

162 

E2 

57856 

226 

23 

8960 

35 

63 

25344 

99 

A3 

41728 

163 

E3 

58112 

227 

24 

9216 

36 

64 

25600 

100 

A4 

41984 

164 

E4 

58368 

228 

25 

9472 

37 

65 

25856 

101 

A5 

42240 

165 

E5 

58624 

229 

26 

9728 

38 

66 

26112 

102 

A6 

42496 

166 

E6 

58880 

230 

27 

9984 

39 

67 

26368 

103 

A7 

42752 

167 

E7 

59136 

231 

28 

10240 

40 

68 

26624 

104 

A8 

43008 

168 

E8 

59392 

232 

29 

10496 

41 

69 

26880 

105 

A9 

43264 

169 

E9 

59648 

233 

2A 

10752 

42 

6A 

27136 

106 

AA 

43520 

170 

EA 

59904 

234 

2B 

11008 

43 

6B 

27392 

107 

AB 

43776 

171 

EB 

60160 

235 

2C 

11264 

44 

6C 

27648 

108 

AC 

44032 

172 

EC 

60416 

236 

2D 

11520 

45 

6D 

27904 

109 

AD 

44288 

173 

ED 

60672 

237 

2E 

11776 

46 

6E 

28160 

110 

AE 

44544 

174 

EE 

60928 

238 

2F 

12032 

47 

6F 

28416 

111 

AF 

44800 

175 

EF 

61184 

239 

30 

12288 

48 

70 

28672 

112 

B0 

45056 

176 

F0 

61440 

240 

31 

12544 

49 

71 

28928 

113 

B1 

45312 

177 

FI 

61696 

241 

32 

12800 

50 

72 

29184 

114 

B2 

45568 

178 

F2 

61952 

242 

33 

13056 

51 

73 

29440 

115 

B3 

45824 

179 

F3 

62208 

243 

34 

13312 

52 

74 

29696 

116 

B4 

46080 

180 

F4 

62464 

244 

35 

13568 

53 

75 

29952 

117 

B5 

46336 

181 

F 5 

62720 

245 

36 

13824 

54 

76 

30208 

118 

B6 

46592 

182 

F6 

62976 

246 

37 

14080 

55 

77 

30464 

119 

B7 

46848 

183 

F7 

63232 

247 

38 

14336 

56 

78 

30720 

120 

B8 

47104 

184 

F8 

63488 

248 

39 

14592 

57 

79 

30976 

121 

B9 

47360 

185 

F9 

63744 

249 

3A 

14848 

58 

7A 

31232 

122 

BA 

47616 

186 

FA 

64000 

250 

3B 

15104 

59 

7B 

31488 

123 

BB 

47872 

187 

FB 

64256 

251 

3C 

15360 

60 

7C 

31744 

124 

BC 

48128 

188 

FC 

64512 

252 

3D 

15616 

61 

7D 

32000 

125 

BD 

48384 

189 

FD 

64768 

253 

3E 

15872 

62 

7E 

32256 

126 

BE 

48640 

190 

FE 

65024 

254 

3F 

16128 

63 

7F 

32512 

127 

BF 

48896 

191 

FF 

65280 

255 



APPENDIX 2 

A Program to Record Composite Tapes 


The assembly language program given below will record a SYSTEM tape of a composite (BASIC and 
assembly language) program constructed in accordance with the directions given in Part II of this book. The 
origin and execution address of the tape it creates will be 42E9H (the beginning of free RAM in Level II). The 
program automatically dumps from this address to the end of any resident BASIC program. (The assembly 
language segments and the BASIC program segment should be loaded into memory as explained in Chapter 
17. Then the following routine will correctly record the composite program. Observe the generous use of 
ROM subroutines in this program.) 


00100 


ORG 

7F60H 


00110 

START 

CALL 

01C9H 

CLEAR SCREEN 

00120 


LD 

HL,TEXT 


00130 


CALL 

28A7H 

DISPLAY PROMPT 

00140 


LD 

HL,41E8H 


00150 


PUSH 

HL 


00160 


LD 

B, 6 


00170 

FILL 

LD 

(HL),20H 

SPACES IN BUFFER 

00180 


INC 

HL 


00190 


DJNZ 

FILL 


00200 


POP 

HL 


00210 


LD 

B, 6 


00220 


CALL 

05D9H 

INPUT TITLE 

00230 


XOR 

A 


00240 


CALL 

0212H 

CASSETTE ON 

00250 


CALL 

0287H 

WRITE LEADER 

00260 


LD 

A.55H 

ID BYTE 

00270 


CALL 

0264H 


00280 


LD 

HL,41E8H 

ADDRESS OF TITLE 

00290 


LD 

B, 6 


00300 

NAME 

LD 

A.(HL) 


00310 


CP 

0DH 

IS IT A C. R.? 

00320 


JR 

NZ.SKIP 


00330 


LD 

A, 20H 

CHANGE TO SPACE 

00340 

SKIP 

CALL 

0264H 

WRITE BYTE 

00350 


INC 

HL 


00360 


DJNZ 

NAME 

LOOP FOR 6 CHARS 

00370 


LD 

HL,42E9H 

*START ADDRESS* 

00380 

LP1 

LD 

DE , 0 

BYTE COUNT 

00390 


LD 

C,0 

CLEAR CHECKSUM 

00400 


LD 

A.3CH 

BLOCK SYNC 

00410 


CALL 

0264H 


00420 


LD 

A. E 

BYTE COUNT 

00430 


CALL 

0264H 


00440 


LD 

A, L 

ADDRESS OF DATA 

00450 


CALL 

0264H 


00460 


LD 

A, H 

ADDRESS OF DATA 

00470 


CALL 

0264H 


00480 


ADD 

A. L 


00490 


ADD 

A. E 


00500 


LD 

C , A 

SAVE CHECKSUM 

00510 

LP2 

LD 

A,(HL) 


00520 


CALL 

0264H 

OUTPUT DATA 

00530 


ADD 

A. C 


00540 


LD 

C , A 

SAVE CHECKSUM 

00550 


INC 

HL 


00560 


DEC 

DE 


00570 


XOR 

A 


00580 


OR 

E 

BLOCK END? 
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00590 


JR 

NZ.LP2 


00600 


LD 

A, C 


00610 


CALL 

0264H 

;OUTPUT CHECKSUM 

00620 


EX 

DE.HL 


00630 


LD 

HL,(40F9H) 

:BASIC END ADDR 

00640 


PUSH 

DE 


00650 


INC 

DE 


00660 


INC 

DE 


00670 


INC 

DE 


00680 


OR 

A 


00690 


SBC 

LLi 

o 

;IS THIS THE END? 

00700 


POP 

HL 


00710 


JP 

P , LP1 


00720 


LD 

A.78H 

;EXECUTE SYNC 

00750 


CALL 

0264H 


00740 


LD 

A.0E9H 

;*ENTRY POINT* 

00750 


CALL 

0264H 


00760 


LD 

A.42H 

;* ENTRY POINT* 

00770 


CALL 

0264H 


00780 


CALL 

01F8H 

;CASSETTE OFF 

00790 


JP 

1A19H 

;LEVEL II RETURN 

00800 

TEXT 

DEFM 

'ENTER THE' 


00810 


DEFM 

' TITLE: ' 


00820 


DEFB 

0 


00830 


END 

START 
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APPENDIX 3 

A Program for Faster Recording of Data Tapes 


Data lists are stored on tape with the BASIC command "PRINT#-1, X". Each time this statement is 
encountered in the program, a new leader and sync byte are generated. The leader is 256 bytes long and takes 
4 seconds to write. The maximum number of bytes of data that may be written with one such command is also 
256 bytes. Thus, under the best conditions half of your tape I/O time is occupied with leader. Typically the 
leader requires an even greater proportion of the time. The assembly language routine given below will write a 
data tape with a short leader. The tape so written may be read back with the standard INPUT#-1 command. 
Because the operations are so fast, it is advisable to disable the automatic control of tape transport and start 
and stop the cassette manually. 

Before you can shorten the tape leaders, you must first write a normal length leader to allow the TRS-80 to 
lock onto your data signal. This may be accomplished by first writing a dummy value to the tape in the 
standard way (PRINT#-1, 0). Then, to activate the custom tape writing routine, use the following (compound) 
statement any place that you would normally use "PRINT#-1, A$": 

500 P%-0 :P%=USR(VARPTR(A$)) 


The first statement ensures that the variable P% has been established in BASIC variable storage so that the 
pointer to the "dope" block of A$ (as fetched by VARPTR) will be true when passed to the assembly language 
subroutine. The second statement calls the assembly language subroutine, which writes the string to tape. The 
"A$" may be replaced by any string name. To write a number to tape, first convert it to a string with the STR$ 
function. To read it back, input it as a string and use the VAL function to convert it to a number again. It may 
be necessary to read all the numeric data before converting to numeric form because the VAL function is slow. 

The following source listing of the assembly language routine contains a linkage initialization segment; this 
routine has been designed to be the first segment of a composite program constructed according to the 


directions given in Chapters 14 and 17. 



00100 


ORG 

42E9H 


00110 


LD 

HL,ENTRY 

LINKAGE 

00120 


LD 

(408EH),HL 

INITIALIZATION 

00130 


LD 

HL , FINIS 

SEGMENT 

00140 


LD 

(40A4H),HL 


00150 


LD 

DE , 65530 


00160 


CALL 

1B2CH 


00170 


INC 

HL 


00180 


INC 

HL 


00190 


LD 

(40F9H),HL 


00200 


LD 

HL,1D1EH 


00210 


PUSH 

HL 


00220 


JP 

185DH 


00230 

ENTRY 

LD 

B, 0AH 

LENGTH OF LEADER 

00240 

LOOP 

XOR 

A 

LEADER BYTE = 0 

00250 


CALL 

0264H 

WRITE BYTE 

00260 


DJNZ 

LOOP 


00270 


LD 

A.0A5H 

SYNC BYTE 

00280 


CALL 

0264H 


00290 


LD 

HL,(41 2 1H) 

"DOPE" POINTER 

00300 


LD 

B,(HL) 

STRING LENGTH 

00310 


INC 

HL 


00320 


LD 

E,(HL) 

STRING ADDRESS 





00330 


INC 

HL 


00340 


LD 

D, (HL) 

;STRING ADDRESS 

00350 

WRITE 

LD 

A, (DE) 

; NEXT CHARACTER 

00360 


CALL 

0264H 

;WRITE TO TAPE 

00370 


INC 

DE 


00380 


DJNZ 

WRITE 


00390 


LD 

A.0DH 

;END BYTE 

00400 


CALL 

0264H 


00410 


RET 



00420 


DEFB 

0 

:BASIC TEXT NEXT 

00430 

FINIS 

DEFS 

0 


00440 


END 




The following BASIC program (to be adjoined to the end of the above routine as explained in Chapter 17) 
is a demonstration program that will create 10 strings, dump them to tape with short leaders, and read them 
back. Note that the printing of a dummy variable requires reading in a dummy variable before the start of the 
actual data. 


100 CLEAR 100 
110 FOR 1=1 TO 10 

120 AS(I)=STR$(100+1) : REM: GENERATE 10 STRINGS 

130 PRINT AS(I):NEXT I 

140 PRINT "PREPARE CASSETTE TO RECORD. THEN PRESS ENTER." 
150 X$=INKEY$:IF X$="" THEN 150 

160 PRINT#-1,0: REM: WRITE DUMMY VARIABLE 

170 FOR 1=1 TO 10 

180 PRINT "WRITING NUMBER";I 

190 REM: BE SURE TO SET UP THE VARIABLE P% FIRST 
200 P%=0:P%=USR(VARPTR(A$(I))): REM: WRITE TO TAPE 
210 NEXT I 

220 PRINT "REWIND THE TAPE AND PRESS ENTER FOR PLAYBACK." 
230 X$=INKEY$:IF X$="" THEN 230 

240 INPUT#-1,N: REM: INPUT DUMMY VARIABLE 

250 FOR 1=1 TO 10:INPUT#-1,AS(I) 

260 PRINT "READING NUMBER";I:NEXT I 
270 FOR 1=1 TO 10:PRINT A$(I):NEXT I 
280 END 


Note that this system writes only one value for each tape command. If you are dealing exclusively with 
numeric variables - several of which can be written with each standard PRINT#-1 statement - this technique 
may not be particularly advantageous. It is of greatest value when dealing with long string variables. 
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